Skip to main content
POST
Rate limit tier: submission, 60 requests/min. See Rate limits. Uploads 1–100 files as a single document packet, the unit a run addresses. Every file lands in one packet. Creation is all-or-nothing: one rejected file fails the whole request and stores nothing. An unsupported type and disguised bytes both cause a rejection. This endpoint uploads without processing. Trigger extraction afterwards with POST /v3/document-packets/{document_packet_id}/run/. To do both in one call, use Upload and Run. Send the files as multipart form data under the files field, repeating the field for a packet with several files. A file above the per-file size cap is rejected before any bytes reach S3. See Files for the cap and the supported formats. Bundle several files only when they form one document, such as a contract and its annexes. Put unrelated documents in separate packets. Retries are safe with Idempotency-Key. Pass any unique string. Retrying the request with the same key replays the original upload, so the API creates no duplicate packet. See Idempotency. Filenames are unique within a workflow. The on_conflict form field decides what a collision does:
  • error, the default. The whole request fails with 409 before anything is uploaded. The response lists the conflicting names and the name each one would take.
  • rename. The colliding file gets a (n) counter before its extension, so contract.pdf becomes contract (1).pdf. Each returned file’s name is then the name it was stored under, and original_name holds the name you uploaded. original_name is null when no rename happened.
Attach caller context with the optional metadata form field. It takes a JSON-encoded object, sent as a string because multipart carries no nested objects. Free text in natural language goes inside it, under the __anyformat_free_text__ key. GET /v3/document-packets/{document_packet_id}/ echoes it back. A top-level key whose name matches an extract-schema field reaches the LLM and becomes the extracted value. See Attaching metadata for the full contract.

Authorizations

Authorization
string
header
required

API key issued from app.anyformat.ai/api-key. Send as Authorization: Bearer <key>.

Headers

Idempotency-Key
string | null

Optional caller-supplied key (Stripe convention). Retrying the request with the same key replays the original upload slots so no duplicate packet is created.

Path Parameters

workflow_id
string
required

Body

multipart/form-data
files
file[]
required

1..100 files forming one document packet.

metadata
string | null

Optional JSON-encoded object of free-form metadata attached to the packet. The extract operator may source datapoints from a top-level key whose name matches a schema field, and from free text in natural language under __anyformat_free_text__.

on_conflict
enum<string>
default:error

How to handle an uploaded filename that already exists in the workflow (filenames are unique within a workflow). error (the default) rejects the whole request with 409 and lists the conflicting names, so a rename is never silent — the caller must opt in. rename accepts the collision and lets the server auto-rename the file by inserting a (n) counter before the extension (invoice.pdf → invoice (1).pdf).

Available options:
error,
rename

Response

Successful Response

Response for the packet-creating uploads (multipart and from-url).

document_packet_id
string
required

Unique identifier of the newly created document packet (hyphenated UUID).

Example:

"069dcc2c-e14c-7606-8000-2ee4fb17b4e1"

workflow_id
string
required

The workflow the packet was created under (hyphenated UUID).

Example:

"0686bb97-8c30-70f0-8000-97669e000eb8"

files
DocumentPacketCreatedFileV3 · object[]
required

Files in the packet, in the order they were provided.