Skip to main content
Examino’s correction pipeline moves from exam setup through file upload, batch copy creation, and AI-powered grading — all driven by the REST API. This guide walks you through every step in order, explains what each call does, and shows you how to recover from the failures most likely to occur in production.
1

Create the exam

Start by creating a new exam record and assigning it to your team. The POST /exams call returns an examId that anchors every subsequent call in this workflow — save it immediately.
Create exam
Once the exam exists, patch it with the title, level, and language so it’s properly labelled in the dashboard and in exported reports.
Update exam settings
Export EXAM_ID as an environment variable right away. Every call in the remaining steps references it, and overwriting it by accident mid-session is a common source of confusion.
2

Validate the rubric in the web app

Before you can upload copies, an instructor must import the exam subject, let Examino generate the grading rubric, and confirm it from the Examino web interface. The API does not expose a rubric-write endpoint — this step is intentionally human-gated.Poll the exam until questionsValidated flips to true:
Check rubric readiness
Response (rubric ready)
Do not proceed to Step 3 until questionsValidated is true. Copies uploaded against an unvalidated rubric will be rejected when you try to launch correction.
3

Upload files

Uploading a file is a two-part process: you first register the file with Examino to obtain a pre-signed upload URL, then push the raw bytes directly to object storage using that URL.
Register file and upload content
The PUT goes directly to object storage and does not count against your Examino API rate limit. You can fire as many parallel uploads as your network allows — saturating this step is almost always faster than serialising it.
Repeat this process for each student copy. Collect all fileId values returned by the registration step; you will attach them to copies in the next step.
4

Create copies

Attach your uploaded files to the exam by creating copy records. You can submit up to 50 copies per request — batch liberally to reduce round-trips.
Create copies (batch)
Set idProvidedByUser to your student information system (SIS) identifier. It is the recommended key for matching Examino results back to your own records after correction completes — results are not returned in submission order.
5

Launch correction

Before launching, verify that your team has enough credits. The cost is 1 credit per started 20-page block per copy — a 12-page copy costs 1 credit, a 45-page copy costs 3.
Check credit balance
Once confirmed, launch correction across all copies in the exam:
Launch correction
Always supply a meaningful idempotencyKey. If the request times out or your scheduler fires twice, replaying the exact same call with the same key returns the original result instead of launching a duplicate correction. See the Idempotency guide for key-design recommendations.
6

Retrieve results

Poll the corrections endpoint every 15–30 seconds. The job is finished when no copy has a status of pending, processing, or retry.
Poll for results
Sample output
Always filter on status === "success" before aggregating scores. Copies with status error have no valid noteTotal — including them in calculations silently corrupts averages and grade distributions.

​
Incident Recovery

Production pipelines encounter network errors, timeouts, and partial failures. The scenarios below cover the most common issues and explain how to recover without duplicating work or losing data.
A failed PUT leaves you with a fileId registered in Examino but backed by no content. Never attach a fileId whose upload did not complete — it will cause the copy to fail correction.Re-register the file from scratch with a new POST /api/v1/uploads call. You will receive a fresh fileId and a new pre-signed URL. Discard the old fileId entirely and repeat the PUT with the new URL.
Copy creation is atomic: either all copies in a batch are created or none are. There is no partial state to untangle.Before retrying, list the existing copies for the exam to check whether the batch landed:
List existing copies
If the copies are already there, do not resubmit the batch. If they are absent, retry the original request in full.
Replay the exact same request with the same idempotencyKey. Examino will detect the duplicate and return the original launch result without creating a second correction or reserving credits again.A response containing "alreadyRegistered": true confirms the original launch went through — no further action is needed.
Replay correction launch
An error status means correction failed for that copy in the current run. Launch a new correction with a new idempotencyKey — Examino will only process copies that haven’t already succeeded, so copies with status: "success" from the previous run are not re-billed and not re-processed.
Retry failed copies
Delete the copy permanently with DELETE /api/v1/copies/{copyId}. Examino automatically releases any credits that were reserved for that copy back to your balance.
Delete a copy
Deletion is permanent and cannot be undone. Confirm the copyId before sending the request.