Upload files
Uploading takes three steps: request an upload address, send the file, confirm the document. An upload address can be written once and is valid for up to 1 hour.
1. Request an upload address
Section titled “1. Request an upload address”POST /api/v1/upload/presignX-API-Key: sk_your_keyContent-Type: application/json{ "filename": "report.docx", "file_size": 45678}| Field | Type | Required | Description |
|---|---|---|---|
filename | string | ✅ | File name; the server determines the file type from the extension |
file_size | integer | ✅ | Exact size in bytes, greater than 0 |
mime_type | string | — | Optional; the server does not use it |
Response:
{ "document_id": "4q8mx2q9z1k7p6ra", "upload_url": "https://upload.example/...", "upload_headers": { "Content-Type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "If-None-Match": "*" }, "finalize_token": "short_lived_token", "expires_in": 3600}2. Send the file
Section titled “2. Send the file”Send a PUT to upload_url with the raw file bytes as the body, and send every header in upload_headers exactly as given.
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous responsecurl --fail-with-body -X PUT "$UPLOAD_URL" \ -H "Content-Type: $UPLOAD_CONTENT_TYPE" \ -H "If-None-Match: *" \ --upload-file "report.docx"Do not send your OmniDoc API key in this step. If the address expires or the transfer fails, request a new one.
3. Confirm the document
Section titled “3. Confirm the document”POST /api/v1/upload/finalizeX-API-Key: sk_your_keyContent-Type: application/json{"finalize_token":"short_lived_token"}On success the document is returned:
{ "document": { "id": "4q8mx2q9z1k7p6ra", "basename": "report.docx", "file_size": 45678, "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "created_at": "2026-10-01T12:00:00Z" }}Only after confirmation does the document enter the file library and become usable for jobs.
File names
Section titled “File names”filename is for display only; do not use it as a path or a unique identifier. The server replaces illegal characters and generates a safe download name for names that are too long.
Errors
Section titled “Errors”| Status | Cause |
|---|---|
400 | Invalid file name or size, or the uploaded size differs from the requested one |
401 | Credential or finalize_token invalid or expired |
403 | The finalize_token belongs to another account |
410 | The uploaded file was not found (transfer incomplete or address expired); request a new address |
413 | Exceeds the per-file size limit |
415 | Unsupported format, or the content does not match the extension |
422 | The Office file is damaged or structurally unsafe |
429 | Too many uploads |
503 | The upload service is temporarily unavailable; try again later |