Skip to main content
POST
Re-evaluate a submission

Authorizations

X-API-Key
string
header
required

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

Idempotency-Key
string

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.

Maximum string length: 255
Example:

"exam-cbse-sci-10a-2026-10-14"

Path Parameters

submissionId
string<uuid>
required

Submission id (UUID).

Body

application/json
question_ids
string[]

Not available yet: re-evaluating single questions returns 422 feature_not_available.

keep_reviewed
boolean

Keep teacher-edited questions as they are (default true).

Response

Accepted: evaluation queued.

Status of one submission. Create, get, lists and the feed all return this shape.

id
string<uuid>
exam_id
string<uuid>
candidate
object
state
string

live for the current submission; replaced or deleted otherwise.

Example:

"live"

replaced_by
string<uuid>

Present when this submission was replaced.

status
enum<string>
Available options:
queued,
processing,
reading,
grading,
graded,
partially_graded,
failed,
cancelled
lane
string

copy (handwritten) or typed.

pages
integer | null

Page count of the handwritten copy.

needs_review
boolean
review_reasons
string[]

Submission-level reasons, e.g. pages_beyond_vision_limit.

finalized
boolean
finalized_at
string<date-time> | null
progress
object | null
queue
object | null

Only while queued.

attempt_count
integer

How many evaluation runs this submission has had.

rubric_version
integer | null
credits_charged
number | null

Charged credits once graded; 0 for a typed submission with only objective answers; null while running or when failed/cancelled.

error
object | null

Only when failed, e.g. copy_unreadable or language_not_supported.

metadata
object | null
created_at
string<date-time>
updated_at
string<date-time>