Skip to main content
Stage bytes for a single granular document operation and receive an opaque handle. Uploads are workspace-free: a caller can parse, classify, extract, or ground a file without a workspace.

​
Endpoint

​
Request

multipart/form-data with a file part. Optional ttl_seconds form field (integer) overrides the default retention window; capped at the server maximum.
With a custom TTL (seconds):
Form fields:
  • file (required) — The document bytes.
  • ttl_seconds (optional) — How long the upload is retained, in seconds. Defaults to 86400 (24 hours); capped at 604800 (7 days). Bytes are deleted at job completion, so the TTL is only the ceiling for an upload that was never consumed.

​
Response

200 OK
Fields:
  • upload_id — Opaque UUID handle; pass this in any document-operation source.
  • file_name — The original filename from the upload.
  • size_bytes — Exact byte count of the staged file.
  • content_hash — SHA-256 hex digest of the file bytes (bare 64-character hex string, no prefix).
  • expires_at — When the upload is deleted if not consumed. Bytes are also deleted at job completion.

​
Using the upload in an operation

Pass the upload_id as the source discriminator in any document-operation:
Uploads are single-use: bytes are deleted once the job that consumes them finishes.

​
Error responses

413 — file_too_large

​
Upload vs workspace file

See Sources and uploads for all three source discriminator types.