Uploads

Create an upload

Declare the exact byte length of the document. The response is a part plan (fixed 16 MiB parts, the last part carries the remainder), an upload_token that authorizes the rest of the lifecycle, and the upload_key the staged object will live under. The same 402 balance pre-check as extract runs here, before any bytes move.

content_length integer required

Exact document size in bytes. Up to 52,428,800 (50 MiB); larger returns document_too_large.

content_type string optional

For example application/pdf.

Response fields

upload_token string

Send it as the x-velrim-upload-token header on every part, complete and abort call. Valid for 1 hour.

upload_key string

The staged object key. After completing, pass it as document.upload_key to /v1/extract or /v1/jobs.

parts array

The plan: part_number (1-based) and size in bytes for every part you must upload.

part_url_template string

The part endpoint with a {part_number} placeholder. complete_url and abort_url name the other two endpoints.

expires_at integer

Unix seconds. When the upload_token stops working.

Upload parts

Send the raw bytes of each planned part, with your API key and the x-velrim-upload-token header. Each part must match its planned size exactly; a mismatch returns 400. Parts can be uploaded in parallel. Keep the returned etag for the complete call.

Complete or abort

Complete with every part_number and etag from the plan; the response confirms the assembled size. Then send document: { "upload_key": … } to `POST /v1/extract` or POST /v1/jobs. DELETE /v1/uploads (with the same token header) abandons the upload and returns 204.

Lifecycle

Part size

16 MiB, fixed. The part plan is not configurable; the last part carries the remainder.

Token

The upload_token is valid for 1 hour from creation. After that, parts, complete and abort are rejected; create a new upload.

Staging

A staged object lives at most 24 hours. The extraction that consumes it deletes it on completion; an unconsumed object is reaped by the 24-hour lifecycle.

Scope

Staged keys are namespaced per account. Another account can never read, consume or delete your staged object.