Get Application Form
Fetch one application form including its full question list with answers.
GET /api/applications/forms/{formId}Returns one application form with its full question list, including the correct and incorrect answers for each question. Use this when you're building a custom in-game grading flow or need to inspect a form in detail.
To discover form IDs in the first place, call GET /api/applications.
The response includes correctAnswer and incorrectAnswers for every question. The workspace API key already grants full workspace access, so exposing the answer key to the key holder is not an escalation — but never embed your API key in a client-side or in-game script where players could extract it. Always proxy through a server.
Headers
Prop
Type
Path Parameters
Prop
Type
curl https://api.rankgun.works/api/applications/forms/j97a6m1abc123def456ghi789jkl012 \
-H "x-api-key: YOUR_API_KEY"Response
200 OK
{
"workspace": {
"id": "ms78tzxrfqjkd371eewp3dcp9s7z28st",
"groupId": 12345678,
"tier": "elite"
},
"form": {
"id": "j97a6m1abc123def456ghi789jkl012",
"name": "Tier 1 Quiz",
"description": "Entry-level rank application.",
"isActive": true,
"targetRankId": 5,
"targetRankName": "Junior Member",
"passPercentage": 70,
"cooldownHours": 24,
"maxSubmissions": null,
"createdAt": 1700000000,
"updatedAt": 1710000000,
"questions": [
{
"id": "k83c2p8xyz789abc456def123ghi012",
"order": 0,
"questionText": "What is RankGun?",
"questionType": "multiple_choice",
"isRequired": true,
"correctAnswer": "A ranking automation platform",
"incorrectAnswers": ["A game", "A bot", "A Discord server"],
"points": 1
}
]
}
}Top-level fields
Prop
Type
form object
Prop
Type
Question object
Prop
Type
Errors
Every error response has the shape:
{ "success": false, "code": "MACHINE_CODE", "error": "Human message" }400 INVALID_FORM_ID
The formId in the URL is not a valid Convex ID format (wrong length or wrong character set).
{
"success": false,
"code": "INVALID_FORM_ID",
"error": "formId must be a valid Convex ID."
}401 MISSING_API_KEY
No x-api-key (or Authorization: Bearer / api_token) header was sent.
{
"success": false,
"code": "MISSING_API_KEY",
"error": "Provide an API key via the x-api-key header."
}403 INVALID_API_KEY
The key was provided but is not recognised.
{
"success": false,
"code": "INVALID_API_KEY",
"error": "API key is invalid or has been regenerated."
}403 WORKSPACE_DEACTIVATED
The key matches a workspace, but the workspace has been deactivated and cannot make API calls.
{
"success": false,
"code": "WORKSPACE_DEACTIVATED",
"error": "This workspace has been deactivated. Contact [email protected]."
}404 FORM_NOT_FOUND
No form with that id exists, or the form exists in a different workspace. We deliberately do not distinguish these two cases — returning a different error for "exists in another workspace" would leak the existence of forms across workspaces.
{
"success": false,
"code": "FORM_NOT_FOUND",
"error": "No application form with id j97a6m1abc123def456ghi789jkl012 exists in this workspace."
}500 INTERNAL_ERROR
Unhandled server error. Safe to retry with exponential backoff.
{
"success": false,
"code": "INTERNAL_ERROR",
"error": "An unexpected error occurred. Try again or contact support."
}