{
"id": "9b2e4f71-5c3a-4d8e-b6f0-1a7c3e5d9b24",
"exam_id": "3f6c1d2e-8b4a-4c7e-9a51-2d0e7b9c4f18",
"candidate": {
"id": "c41a7e93-2f58-4b6d-8e0a-5d9f1b3c7e62",
"external_id": "STU-10A-0142"
},
"state": "live",
"status": "queued",
"lane": "copy",
"pages": 12,
"needs_review": false,
"review_reasons": [],
"finalized": false,
"finalized_at": null,
"progress": {
"step": null,
"questions_done": 0,
"questions_total": 2
},
"queue": {
"position": 3,
"estimated_ready_at": "2026-10-14T06:02:00Z"
},
"attempt_count": 1,
"rubric_version": 1,
"credits_charged": null,
"error": null,
"metadata": {
"centre": "Jaipur-02"
},
"created_at": "2026-10-14T05:58:41Z",
"updated_at": "2026-10-14T05:58:41Z",
"quote": {
"unit": "page",
"pages": 12,
"credits": 12,
"rate_source": "standard"
},
"warnings": []
}{
"error": {
"code": "malformed_json",
"message": "The request body is not valid JSON for this endpoint.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this evaluation.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "not_found",
"message": "The resource was not found.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Create a submission
Submits one candidate’s work for AI evaluation and returns 202 with the submission and its fixed-price quote.
- Handwritten exams: send
upload_idof areadyupload. Copies of up to 40 pages are read normally; 41 to 80 pages are accepted but flagged for review (pages_beyond_vision_limit); more than 80 pages return 422too_many_pages. - Typed exams: send
answers, each keyed byquestion_idorquestion_label. Long answers are plain text up to 20,000 characters. An answer in which more than 20% of the letters are Devanagari returns 422language_not_supported.
Identify the candidate with candidate_id or an inline candidate (created and registered if new). One live submission per candidate per exam: a second one returns 409 submission_exists unless you send replace: true. The exam must be open (409 exam_not_open).
Scope: evaluation:write
{
"id": "9b2e4f71-5c3a-4d8e-b6f0-1a7c3e5d9b24",
"exam_id": "3f6c1d2e-8b4a-4c7e-9a51-2d0e7b9c4f18",
"candidate": {
"id": "c41a7e93-2f58-4b6d-8e0a-5d9f1b3c7e62",
"external_id": "STU-10A-0142"
},
"state": "live",
"status": "queued",
"lane": "copy",
"pages": 12,
"needs_review": false,
"review_reasons": [],
"finalized": false,
"finalized_at": null,
"progress": {
"step": null,
"questions_done": 0,
"questions_total": 2
},
"queue": {
"position": 3,
"estimated_ready_at": "2026-10-14T06:02:00Z"
},
"attempt_count": 1,
"rubric_version": 1,
"credits_charged": null,
"error": null,
"metadata": {
"centre": "Jaipur-02"
},
"created_at": "2026-10-14T05:58:41Z",
"updated_at": "2026-10-14T05:58:41Z",
"quote": {
"unit": "page",
"pages": 12,
"credits": 12,
"rate_source": "standard"
},
"warnings": []
}{
"error": {
"code": "malformed_json",
"message": "The request body is not valid JSON for this endpoint.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this evaluation.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "not_found",
"message": "The resource was not found.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Authorizations
Your institute's API key, vak_eval_ followed by 48 hex characters. An institute admin creates keys in the dashboard under Settings -> Integrations -> API keys.
Headers
Optional. Any unique string of 1-255 printable ASCII characters (a UUID works). Retrying with the same key within 48 hours replays the first response with Idempotent-Replayed: true.
255"exam-cbse-sci-10a-2026-10-14"
Path Parameters
Exam id (UUID).
Body
Inline candidate (created or updated by external_id). Send this or candidate_id.
Show child attributes
Show child attributes
Evalezy candidate id. Send this or candidate.
Handwritten exams: the id of a ready upload.
Replace the candidate's existing live submission (not allowed once finalized).
A JSON object of your own, up to 2 KB, returned on the submission.
Not available yet (422 feature_not_available).
Not available yet (422 feature_not_available).
Typed exams: one entry per answered question.
Show child attributes
Show child attributes
Response
Accepted: evaluation queued.
Status of one submission. Create, get, lists and the feed all return this shape.
Show child attributes
Show child attributes
live for the current submission; replaced or deleted otherwise.
"live"
Present when this submission was replaced.
queued, processing, reading, grading, graded, partially_graded, failed, cancelled copy (handwritten) or typed.
Page count of the handwritten copy.
Submission-level reasons, e.g. pages_beyond_vision_limit.
Show child attributes
Show child attributes
Only while queued.
Show child attributes
Show child attributes
How many evaluation runs this submission has had.
Charged credits once graded; 0 for a typed submission with only objective answers; null while running or when failed/cancelled.
Only when failed, e.g. copy_unreadable or language_not_supported.
Show child attributes
Show child attributes
The fixed price of this evaluation, known before grading.
Show child attributes
Show child attributes
Show child attributes
Show child attributes