Skip to main content
POST
Rate limit tier: submission, 60 requests/min. See Rate limits. Uploads 1–100 files as a single document packet and enqueues a run on the workflow’s latest version. It composes Upload and Run packet into one call, the shortest path from bytes to structured data. The 202 response returns the new run_id. Poll GET /v3/runs/{run_id}/ until status is terminal. The results arrive inline on that same read. Send the files as multipart form data under the files field, repeating it for a packet with several files. A file above the per-file size cap is rejected before any bytes reach S3. Packet creation is all-or-nothing. Retries are safe with Idempotency-Key. Retrying with the same key replays the original packet and run. The API stores no duplicate upload and bills no second extraction. See Idempotency. Filenames are unique within a workflow. The on_conflict form field decides what a collision does. Under the default, error, a colliding filename fails the request with 409 before anything is uploaded or run. Pass rename to rename instead, so invoice.pdf becomes invoice (1).pdf. This 202 response returns only the run_id, so read the stored names from GET /v3/document-packets/{document_packet_id}/. 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. The value flows into this run’s extract prompt as a “Document Metadata” section. A top-level key whose name matches an extract-schema field reaches the LLM and becomes the extracted value. GET /v3/document-packets/{document_packet_id}/ echoes the metadata back. See Attaching metadata. An organization without extraction credit receives 402 PAYMENT_REQUIRED.

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 packet AND run — no duplicate upload, no second extraction.

X-Anyformat-Priority
string | null

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

202 response for both run triggers (upload/run/ and document-packets/{id}/run/).

run_id
string
required

Unique identifier of the new run (hyphenated UUID).

Example:

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

document_packet_id
string
required

The document packet the run executes on (hyphenated UUID).

Example:

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

workflow_id
string
required

The workflow being run (hyphenated UUID).

Example:

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

status
enum<string>
required

Status at acceptance time — normally queued.

Available options:
queued,
in_progress,
processed,
error,
cancelled
Example:

"queued"