> ## 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 uploads > 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. PDF only, up to 50 MB each. Image types return 422 `feature_not_available`. On an idempotent replay the URLs are not repeated (`upload_url_redacted: true`); request new uploads instead. **Scope:** `evaluation:write` ## OpenAPI ````yaml /api-reference/openapi.json post /uploads 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: /uploads: post: tags: - Uploads summary: Create uploads description: >- 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. PDF only, up to 50 MB each. Image types return 422 `feature_not_available`. On an idempotent replay the URLs are not repeated (`upload_url_redacted: true`); request new uploads instead. **Scope:** `evaluation:write` operationId: createUploads parameters: - 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/CreateUploads' examples: single: summary: One answer copy value: filename: STU-10A-0142-science.pdf content_type: application/pdf size_bytes: 4718592 batch: summary: A bundle of copies value: files: - filename: STU-10A-0142-science.pdf content_type: application/pdf size_bytes: 4718592 - filename: STU-10A-0143-science.pdf content_type: application/pdf size_bytes: 5242880 required: true responses: '201': description: Created content: application/json: schema: type: object properties: uploads: type: array items: $ref: '#/components/schemas/UploadTicket' example: uploads: - id: e7d35b19-04c2-4a8f-93e6-b1f2c8a4d057 filename: STU-10A-0142-science.pdf upload_url: https://uploads.example-storage.com/eval/...signed... method: PUT headers: Content-Type: application/pdf expires_at: '2026-10-14T06:58:41Z' status: pending '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' components: schemas: CreateUploads: type: object properties: files: type: array items: $ref: '#/components/schemas/UploadFile' description: Up to 100 files. Send either `files` or one file at the top level. filename: type: string content_type: type: string description: Must be `application/pdf`. size_bytes: type: integer format: int64 description: Exact file size in bytes. At most 50 MB (52,428,800 bytes). sha256: type: string description: 'Optional: 64 hex characters.' UploadTicket: type: object properties: id: type: string format: uuid description: Upload id. Pass it as `upload_id` when you submit. filename: type: string upload_url: type: string description: Presigned URL. PUT the raw PDF bytes here with the returned headers. method: type: string example: PUT headers: type: object additionalProperties: type: string description: Send these headers with the PUT. expires_at: type: string format: date-time description: The URL is valid for 1 hour. status: type: string example: pending upload_url_redacted: type: boolean description: >- Only on an idempotent replay: the URL is not repeated. Request a new upload. UploadFile: type: object properties: filename: type: string content_type: type: string description: Must be `application/pdf`. size_bytes: type: integer format: int64 description: Exact file size in bytes. At most 50 MB. sha256: type: string description: 'Optional: 64 hex characters.' 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 responses: 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 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 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.