> ## Documentation Index > Fetch the complete documentation index at: https://docs.evalezy.com/llms.txt > Use this file to discover all available pages before exploring further. # 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_id` of a `ready` upload. 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 422 `too_many_pages`. - **Typed exams:** send `answers`, each keyed by `question_id` or `question_label`. Long answers are plain text up to 20,000 characters. An answer in which more than 20% of the letters are Devanagari returns 422 `language_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` ## OpenAPI ````yaml /api-reference/openapi.json post /exams/{examId}/submissions openapi: 3.0.1 info: title: Evalezy AI Evaluation API version: v1 description: >- Create exams, register candidates, submit scanned answer copies or typed answers, and read question-wise AI marks with feedback. Results are drafts until you finalize them. Server-to-server only: never ship an API key inside a browser or mobile app. English answers only for now (Hindi and regional languages are on the roadmap). contact: name: Evalezy email: hello@evalezy.com url: https://evalezy.com servers: - url: https://api.evalezy.com/v1 description: Production security: - ApiKey: [] tags: - name: Exams description: Create, open, edit and look up exams. - name: Questions description: Add, edit and remove the questions of an exam. - name: Rubrics description: Marking criteria and model answers for long-answer questions. - name: Choice groups description: Internal choice ("attempt any N of M"). Beta, enabled on request. - name: Candidates description: >- Your students, keyed by your own external_id, and their exam registrations. - name: Uploads description: Presigned uploads for scanned answer copies (PDF). - name: Submissions description: Submit a copy or typed answers for a candidate and track its evaluation. - name: Results description: Question-wise marks, feedback and the checked (annotated) copy. - name: Review description: Teacher overrides, approval, finalize and unfinalize. - name: Credits description: Credit balance, rate card and price quotes. - name: Account description: Check which institute and scopes an API key has. paths: /exams/{examId}/submissions: post: tags: - Submissions summary: Create a submission description: >- Submits one candidate's work for AI evaluation and returns `202` with the submission and its fixed-price `quote`. - **Handwritten exams:** send `upload_id` of a `ready` upload. 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 422 `too_many_pages`. - **Typed exams:** send `answers`, each keyed by `question_id` or `question_label`. Long answers are plain text up to 20,000 characters. An answer in which more than 20% of the letters are Devanagari returns 422 `language_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` operationId: createSubmission parameters: - name: examId in: path required: true schema: type: string format: uuid description: Exam id (UUID). - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 example: exam-cbse-sci-10a-2026-10-14 description: >- 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`. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSubmission' examples: handwritten: summary: Handwritten copy value: candidate: external_id: STU-10A-0142 name: Aarav Sharma roll_number: '14' upload_id: e7d35b19-04c2-4a8f-93e6-b1f2c8a4d057 metadata: centre: Jaipur-02 typed: summary: Typed answers value: candidate: external_id: aspirant-58213 name: Neha Verma answers: - question_label: Q1 text: >- Fiscal federalism refers to the division of taxation powers and expenditure responsibilities between the Union and the states. The Finance Commission, constituted under Article 280... required: true responses: '202': description: 'Accepted: evaluation queued.' content: application/json: schema: $ref: '#/components/schemas/SubmissionCreated' example: 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: [] '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' components: schemas: CreateSubmission: type: object properties: candidate: $ref: '#/components/schemas/CandidateInput' description: >- Inline candidate (created or updated by `external_id`). Send this or `candidate_id`. candidate_id: type: string description: Evalezy candidate id. Send this or `candidate`. upload_id: type: string description: 'Handwritten exams: the id of a `ready` upload.' replace: type: boolean description: >- Replace the candidate's existing live submission (not allowed once finalized). metadata: $ref: '#/components/schemas/JsonNode' description: A JSON object of your own, up to 2 KB, returned on the submission. images: type: array items: type: string description: Not available yet (422 `feature_not_available`). files: type: array items: type: string description: Not available yet (422 `feature_not_available`). answers: type: array items: $ref: '#/components/schemas/AnswerInput' description: 'Typed exams: one entry per answered question.' SubmissionCreated: allOf: - $ref: '#/components/schemas/Submission' - type: object properties: quote: $ref: '#/components/schemas/SubmissionQuote' warnings: type: array items: $ref: '#/components/schemas/Warning' CandidateInput: type: object properties: external_id: type: string description: Your id for the candidate (required), up to 128 characters. name: type: string description: Up to 255 characters, no `<` or `>`. roll_number: type: string description: Up to 64 characters. section_or_class: type: string description: Up to 64 characters. metadata: $ref: '#/components/schemas/JsonNode' description: A JSON object of your own, up to 2 KB. JsonNode: type: object AnswerInput: type: object properties: question_id: type: string description: Question id. Send this or `question_label`. question_label: type: string description: Question label. Send this or `question_id`. text: type: string description: '`long_answer`: plain text, up to 20,000 characters.' option_labels: type: array items: type: string description: 'MCQ and true/false: the chosen option labels.' value: $ref: '#/components/schemas/JsonNode' description: '`numeric`: a number. `one_word`: a string.' Submission: type: object description: >- Status of one submission. Create, get, lists and the feed all return this shape. properties: id: type: string format: uuid exam_id: type: string format: uuid candidate: $ref: '#/components/schemas/CandidateRef' state: type: string description: >- `live` for the current submission; `replaced` or `deleted` otherwise. example: live replaced_by: type: string format: uuid description: Present when this submission was replaced. status: type: string enum: - queued - processing - reading - grading - graded - partially_graded - failed - cancelled lane: type: string description: '`copy` (handwritten) or `typed`.' pages: type: integer nullable: true description: Page count of the handwritten copy. needs_review: type: boolean review_reasons: type: array items: type: string description: Submission-level reasons, e.g. `pages_beyond_vision_limit`. finalized: type: boolean finalized_at: type: string format: date-time nullable: true progress: type: object nullable: true properties: step: type: string nullable: true questions_done: type: integer questions_total: type: integer estimated_ready_at: type: string format: date-time queue: type: object nullable: true description: Only while `queued`. properties: position: type: integer estimated_ready_at: type: string format: date-time nullable: true attempt_count: type: integer description: How many evaluation runs this submission has had. rubric_version: type: integer nullable: true credits_charged: type: number nullable: true description: >- Charged credits once graded; 0 for a typed submission with only objective answers; null while running or when failed/cancelled. error: type: object nullable: true description: >- Only when `failed`, e.g. `copy_unreadable` or `language_not_supported`. properties: code: type: string message: type: string metadata: type: object nullable: true additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time SubmissionQuote: type: object description: The fixed price of this evaluation, known before grading. properties: unit: type: string enum: - page - answer pages: type: integer description: 'Handwritten: pages of the PDF.' answers: type: integer description: 'Typed: non-blank long answers.' credits: type: number nullable: true rate_source: type: string nullable: true description: '`standard` or `contract`.' Warning: type: object description: >- A non-fatal note about the request, e.g. `auto_rubric` or `pages_beyond_vision_limit`. properties: code: type: string message: type: string field: type: string nullable: true Error: type: object description: >- Every error uses this envelope. Branch on `error.code`; the message is for humans. properties: error: type: object properties: code: type: string description: Stable machine code, e.g. `validation_failed`. example: validation_failed message: type: string description: Human-readable explanation. example: questions[1].max_marks must be a multiple of 0.5. request_id: type: string description: >- Quote this when you contact support (also sent as the X-Request-Id header). details: type: object description: >- Extra context. For `validation_failed`, `details.errors` lists every failing field. additionalProperties: true CandidateRef: type: object properties: id: type: string format: uuid description: Evalezy candidate id. external_id: type: string description: Your id for the candidate. responses: Error400: description: Malformed JSON or invalid cursor. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: malformed_json message: The request body is not valid JSON for this endpoint. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f Error401: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: The API key is not valid. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f Error402: description: Not enough credits for this evaluation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_credits message: Not enough credits for this evaluation. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f Error403: description: >- The key lacks the required scope, or the API is not enabled for the institute. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope message: This API key lacks the evaluation:write scope. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f details: required_scope: evaluation:write Error404: description: Not found (ids of other institutes are also 404). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: The resource was not found. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f Error409: description: Conflict with the current state. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conflict message: The request conflicts with the current state. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f Error422: description: The request is valid JSON but breaks a rule. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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. Error429: description: Rate limit or daily quota reached. Retry after the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Too many requests. Retry after 2 s. request_id: req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.