Skip to content

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.

POST /api/v1/upload/presign
X-API-Key: sk_your_key
Content-Type: application/json
{
"filename": "report.docx",
"file_size": 45678
}
FieldTypeRequiredDescription
filenamestring✅File name; the server determines the file type from the extension
file_sizeinteger✅Exact size in bytes, greater than 0
mime_typestring—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
}

Send a PUT to upload_url with the raw file bytes as the body, and send every header in upload_headers exactly as given.

Terminal window
# UPLOAD_URL and UPLOAD_CONTENT_TYPE come from upload_url and upload_headers["Content-Type"] in the previous response
curl --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.

POST /api/v1/upload/finalize
X-API-Key: sk_your_key
Content-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.

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.

StatusCause
400Invalid file name or size, or the uploaded size differs from the requested one
401Credential or finalize_token invalid or expired
403The finalize_token belongs to another account
410The uploaded file was not found (transfer incomplete or address expired); request a new address
413Exceeds the per-file size limit
415Unsupported format, or the content does not match the extension
422The Office file is damaged or structurally unsafe
429Too many uploads
503The upload service is temporarily unavailable; try again later