Skip to main content
POST
Rate limit tier: submission (60 req/min) — see Rate limits. Uploads 1–10 files as a single document packet — the unit that runs later address. All files are grouped into one packet; creation is all-or-nothing, so any rejected file (unsupported type, disguised bytes) fails the whole request and nothing is stored. This endpoint uploads without processing. Trigger extraction afterwards via POST /v3/document-packets/{document_packet_id}/run/ — or do both in one call with Upload and Run. Send the files as multipart form data under the files field (repeat the field for a multi-file packet). Files above the per-file size cap are rejected at slot mint (before any bytes reach S3); see Files for the cap and supported formats. Bundle multiple files only when they belong together as one document (a contract and its annexes) — unrelated documents should be separate packets.
Retries are safe with Idempotency-Key. Pass any unique string; retrying the request with the same key replays the original upload, so no duplicate packet is created. See Idempotency.
Filenames are unique within a workflow, controlled by the on_conflict form field:
  • error (default) — if a file’s name matches one already in the workflow, the whole request fails with 409 before anything is uploaded, listing the conflicting names and the name each would take.
  • rename — the colliding file is auto-renamed by inserting a (n) counter before the extension (contract.pdfcontract (1).pdf). Each returned file’s name is then the name it was actually stored under, and original_name holds the name you uploaded (and is null when no rename happened).
Attach caller context with the metadata form field. Optional; a JSON-encoded object stapled to the packet (multipart can’t carry nested objects natively, so send the JSON as a string). Echoed back on GET /v3/document-packets/{document_packet_id}/; a top-level key whose name matches an extract-schema field is surfaced to the LLM and used as 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..10 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.

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.pdfinvoice (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.