# Evalezy API

> AI evaluation of handwritten answer copies and typed long answers, with teacher review and finalize.

- [Introduction](https://docs.evalezy.com/introduction.md): Grade handwritten answer copies and typed long answers with AI, from your own exam system.
- [Quickstart](https://docs.evalezy.com/quickstart.md): Create a typed exam, submit an answer, read the AI marks and finalize them. Then do the same for a handwritten copy.
- [Authentication](https://docs.evalezy.com/authentication.md): Authenticate with an API key in the X-API-Key header, choose its scopes and keep it safe.
- [Exams and questions](https://docs.evalezy.com/concepts/exams-and-questions.md): Model a question paper as an exam: its mode, its questions, and the draft-to-open lifecycle that freezes the marking scheme.
- [Rubrics and model answers](https://docs.evalezy.com/concepts/rubrics.md): Tell the grader how marks are earned on long-answer questions, with criteria that add up to the question's max marks.
- [Candidates](https://docs.evalezy.com/concepts/candidates.md): Identify students by your own ids, register them on exams, and send only the personal data you need.
- [Uploads](https://docs.evalezy.com/concepts/uploads.md): Send handwritten answer sheets as PDFs through short-lived presigned URLs, then check that each file is ready before you submit it.
- [Submissions](https://docs.evalezy.com/concepts/submissions.md): Submit one candidate's handwritten copy or typed answers for grading, follow it through the queue, and replace, cancel, delete or re-evaluate it.
- [Results](https://docs.evalezy.com/concepts/results.md): Read question-wise marks and feedback, review what the AI was unsure about, override or approve marks, download the checked copy, and finalize results.
- [Handwritten term exams](https://docs.evalezy.com/guides/handwritten-exams.md): Grade a school's scanned answer sheets, from the marking scheme to the report card.
- [Typed online tests](https://docs.evalezy.com/guides/typed-tests.md): Grade typed answers the moment a student submits, and show marks and feedback in your test player.
- [Daily answer-writing practice](https://docs.evalezy.com/guides/answer-writing-practice.md): Run a UPSC-style daily answer-writing programme: one question a day, handwritten answers, feedback and a model answer for every student.
- [Syncing results](https://docs.evalezy.com/guides/syncing-results.md): Keep your system in step with every grading result using one polling worker, until webhooks arrive.
- [Going live](https://docs.evalezy.com/guides/going-live.md): The checklist to work through before your integration grades its first real exam.
- [Pricing and credits](https://docs.evalezy.com/platform/pricing.md): Fixed prices you know before grading: per page for handwritten copies, per long answer for typed ones. Check your balance and quote a job before you submit it.
- [Errors](https://docs.evalezy.com/platform/errors.md): One error envelope for every failed request, a stable machine code to branch on, and a request id to quote when you need help.
- [Rate limits and quotas](https://docs.evalezy.com/platform/rate-limits.md): Per-second and per-minute request limits per key and per institute, a daily copy quota per institute, and the headers that tell you where you stand.
- [Idempotency and safe retries](https://docs.evalezy.com/platform/idempotency.md): Retry any request without creating a second exam, a duplicate submission or a double charge, using the Idempotency-Key header and the API's natural keys.
- [Pagination and syncing](https://docs.evalezy.com/platform/pagination.md): Cursor-based lists ordered by last change, the updated_since filter, and a sync loop that never misses or double-processes a submission.
- [Changelog](https://docs.evalezy.com/platform/changelog.md): What changed in the Evalezy Evaluation API, newest first.
- [Roadmap](https://docs.evalezy.com/platform/roadmap.md): What is planned for the Evaluation API but not available yet, and what to do in the meantime.
- [API reference](https://docs.evalezy.com/api-reference/introduction.md): Base URL, authentication and the conventions every Evalezy endpoint follows.
- [Set a question's rubric](https://docs.evalezy.com/api-reference/rubrics/set-a-questions-rubric.md): Sets or clears one long-answer question's rubric and/or model answer. Send `{"rubric": null}` to clear the rubric. The same rules as [Update several rubrics](/api-reference/rubrics/update-several) apply.
- [List rubrics](https://docs.evalezy.com/api-reference/rubrics/list-rubrics.md): Returns the rubrics and model answers of an exam's long-answer questions, with the current rubric version.
- [Update several rubrics](https://docs.evalezy.com/api-reference/rubrics/update-several.md): Sets or clears the rubric and/or model answer of several long-answer questions in one version bump. The body maps question ids to `{rubric, model_answer}`; send `null` to clear one.
- [Replace choice groups (beta)](https://docs.evalezy.com/api-reference/choice-groups/replace-choice-groups-beta.md): **Beta, enabled on request.** Choice groups are currently switched off, so this endpoint returns 422 `feature_not_available`; send papers without internal choice for now, or contact hello@evalezy.com if you need them.
- [Create uploads](https://docs.evalezy.com/api-reference/uploads/create-uploads.md): Returns presigned upload URLs for one PDF (top-level fields) or up to 100 PDFs (`files`). Each URL is valid for 1 hour. PUT the raw file bytes to `upload_url` with the returned `headers`, then pass the upload `id` as `upload_id` when you submit.
- [Get an upload](https://docs.evalezy.com/api-reference/uploads/get-an-upload.md): Returns an upload. The first read after your PUT checks the file (size, type, page count): the status becomes `ready` with `pages`, or `rejected` with a `reject_reason`. A file still not uploaded stays `pending` until its URL expires.
- [Unfinalize a submission](https://docs.evalezy.com/api-reference/review/unfinalize-a-submission.md): Puts a finalized result back on hold so it can be reviewed or re-evaluated. `reason` is required and recorded. A submission that is not finalized returns 409 `submission_not_finalized`.
- [Approve a submission](https://docs.evalezy.com/api-reference/review/approve-a-submission.md): Marks the AI marks as reviewed without changes, which clears `needs_review`. The body is optional.
- [Finalize results](https://docs.evalezy.com/api-reference/review/finalize-results.md): Publishes AI draft marks as final. Send `submission_ids` (up to 500) or `all_graded: true`. Graded submissions are finalized; `partially_graded` and `failed` ones only with `allow_partial` (failed questions count 0); queued or running ones are skipped. After finalize, overrides and re-evaluate retur…
- [Override a question's marks](https://docs.evalezy.com/api-reference/review/override-a-questions-marks.md): Sets a teacher's marks and feedback for one question. `awarded` must be between 0 and the question's max, in steps of 0.5 (422 `invalid_marks`). The reviewer and reason are shown in the dashboard. A finalized submission returns 409 `submission_finalized`.
- [Re-evaluate a submission](https://docs.evalezy.com/api-reference/submissions/re-evaluate-a-submission.md): Grades the whole copy again, for example after you change the rubric. **Charged again** at the same fixed price. With `keep_reviewed` (default `true`) questions a teacher edited keep their marks. A finalized submission returns 409 `submission_finalized`; one still being evaluated returns 409 `evalua…
- [Cancel an evaluation](https://docs.evalezy.com/api-reference/submissions/cancel-an-evaluation.md): Cancels a queued or running evaluation. Cancelled evaluations are not billed. A finished one returns 409 `already_completed`. Returns `{"id": "...", "status": "cancelled"}`.
- [List an exam's submissions](https://docs.evalezy.com/api-reference/submissions/list-an-exams-submissions.md): Lists an exam's submissions ordered by `(updated_at, id)`. Filter by `status`, `needs_review`, `finalized`, `candidate_id` or `updated_since`. `include=result` adds each live submission's full result.
- [Create a submission](https://docs.evalezy.com/api-reference/submissions/create-a-submission.md): Submits one candidate's work for AI evaluation and returns `202` with the submission and its fixed-price `quote`.
- [Submission feed](https://docs.evalezy.com/api-reference/submissions/submission-feed.md): All submissions of the institute across exams, ordered by `(updated_at, id)`. `updated_since` is required. Poll this feed to pick up status changes: store the last `updated_at` you processed and follow `next_cursor` until `has_more` is false.
- [Get a submission](https://docs.evalezy.com/api-reference/submissions/get-a-submission.md): Returns a submission's status, with queue position and estimated ready time while it is queued.
- [Delete a submission](https://docs.evalezy.com/api-reference/submissions/delete-a-submission.md): Deletes a submission that is not finalized, for example a wrong upload. Any running evaluation is cancelled. Returns `{"id": "...", "deleted": true}`.
- [List exams](https://docs.evalezy.com/api-reference/exams/list-exams.md): Lists the exams this institute created through the API, ordered by last change. Exams created in the dashboard are not listed.
- [Create an exam](https://docs.evalezy.com/api-reference/exams/create-an-exam.md): Creates an exam with its questions, and optionally registers candidates in the same call. The exam starts as a `draft`; send `open: true` to open it right away (or call [Open an exam](/api-reference/exams/open) later).
- [Open an exam](https://docs.evalezy.com/api-reference/exams/open.md): Opens a draft exam so it accepts submissions. The exam needs at least one question, and every rubric must add up to its question's max marks. Opening an exam that is already open changes nothing.
- [Find exams by external_ref](https://docs.evalezy.com/api-reference/exams/search.md): Looks up exams by your own `external_ref` values (1 to 500 per call). Returns `{"data": [...]}` with the exams found.
- [Get an exam](https://docs.evalezy.com/api-reference/exams/get-an-exam.md): Returns one exam. Use `include` to add `questions`, `candidates`, `choice_groups`, `stats` or `rubric`. Deleted exams are returned with status `deleted`.
- [Delete an exam](https://docs.evalezy.com/api-reference/exams/delete-an-exam.md): Deletes a draft exam, or an open exam that has no submissions. An exam with submissions returns 409 `exam_has_submissions`. Returns `{"id": "...", "status": "deleted"}`.
- [Update an exam](https://docs.evalezy.com/api-reference/exams/update-an-exam.md): Edits exam fields. Until the exam is finalized you can change `title`, `external_ref`, `conducted_on`, `subject`, `board`, `class`, `level`, `instructions` and `feedback_language`. `sections`, `blind` and `mode` can change only while the exam is a draft. `answer_language` and `status` cannot be chan…
- [List questions](https://docs.evalezy.com/api-reference/questions/list-questions.md): Returns `{"questions": [...]}` in paper order. Add `include=rubric,model_answer` to include marking material.
- [Add questions](https://docs.evalezy.com/api-reference/questions/add-questions.md): Adds questions to a draft exam. Labels must be unique across the exam. An open exam returns 409 `exam_open`.
- [Delete a question](https://docs.evalezy.com/api-reference/questions/delete-a-question.md): Removes a question from a draft exam. Returns `{"id": "...", "deleted": true}`.
- [Update a question](https://docs.evalezy.com/api-reference/questions/update-a-question.md): Edits one question. In a draft exam any field can change except `type` and `section`. Once the exam is open, only `text`, `model_answer`, `rubric`, `tags`, `word_limit` and `expects_diagram` can change.
- [List an exam's candidates](https://docs.evalezy.com/api-reference/candidates/list-an-exams-candidates.md): Lists the candidates registered on an exam, each with their latest submission id and status.
- [Register candidates on an exam](https://docs.evalezy.com/api-reference/candidates/register-candidates-on-an-exam.md): Registers candidates on an exam. Send `candidates` (created or updated by `external_id` first) or `candidate_ids` (up to 2,000). Returns `registered`, `already_registered` and `candidates`. You can also skip this step: submitting for an inline candidate registers them.
- [Create or update candidates](https://docs.evalezy.com/api-reference/candidates/create-or-update-candidates.md): Creates or updates up to 2,000 candidates by your `external_id`. Returns `{"candidates": [{"id", "external_id", "created"}]}`.
- [Find candidates by external_id](https://docs.evalezy.com/api-reference/candidates/search.md): Looks up candidates by your `external_id` values (1 to 500 per call). Returns `{"data": [...]}`.
- [Get a candidate](https://docs.evalezy.com/api-reference/candidates/get-a-candidate.md): Returns one candidate by Evalezy id.
- [Unregister a candidate](https://docs.evalezy.com/api-reference/candidates/unregister-a-candidate.md): Removes a candidate from an exam. A candidate who already has a submission returns 409 `candidate_has_submission`.
- [Quote a price](https://docs.evalezy.com/api-reference/credits/quote-a-price.md): Quotes the fixed price before you submit. Send exactly one of `pages`, `upload_ids` (exact page counts of 1 to 100 uploads) or `typed_answers`. `sufficient` tells you whether the available credits cover it.
- [Get credit balance](https://docs.evalezy.com/api-reference/credits/get-credit-balance.md): Returns the institute's credit balance, credits committed to queued and running evaluations, what is available, the rate card and the last 30 days' spend.
- [Get a result](https://docs.evalezy.com/api-reference/results/get-result.md): Question-wise marks, criteria, feedback and totals for one submission. Marks are drafts until you finalize. `extracted_answer` (what the AI read) is included by default; add `include=annotations,model_answer` for more.
- [Download the checked copy](https://docs.evalezy.com/api-reference/results/download-the-checked-copy.md): Returns the checked (annotated) copy as a PDF. With `redirect=true` you may get a `302` to a short-lived link instead. No checked copy yet returns 404 `checked_copy_not_found`.
- [List an exam's results](https://docs.evalezy.com/api-reference/results/list-exam-results.md): One result per live submission of the exam, in the same shape as [Get a result](/api-reference/results/get-result). `limit` is 1-50 (default 20). Filter with `finalized` and `updated_since`. `format=csv` is not available yet.
- [Check your API key](https://docs.evalezy.com/api-reference/account/check-your-api-key.md): Returns the key's id, name, institute, scopes, rate tier and today's copy quota. Any valid key can call it; use it to test a new key.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.