Extract structured data from documents
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Query parameters
Request
The shape to extract, as a JSON Schema object. Send action instead to use a saved shape, or neither to have one inferred.
The root must be {"type": "object"}. The dialect is deliberately narrow — no \$ref, \$defs, oneOf, anyOf, allOf, const or pattern — with a maximum nesting depth of 5 and a 64 KB size limit. Make primitives nullable ({"type": ["string", "null"]}) so a missing value reads as null rather than a hallucination.
A saved action to run, by id or slug. An alternative to schema.
The action carries the output shape and any saved settings. Config you send inline on the same call is merged over it, so action plus instructions refines a saved action for one run without redefining it.
Prose guidance for schema inference — only valid when you send neither schema nor action.
Say what the documents are and what matters in them (“freight bills of lading; I care about the load number, the shipper and the total”) and the shape is inferred from the document itself. Sending hints alongside schema or action is a 400: the shape is already decided.
Free-form guidance for the extraction, applied on top of the schema — house rules, formatting preferences, how to handle ambiguity.
Whether to ground each extracted value in the source document. On by default.
When on, output.citations maps every JSON path in the result to where it came from — fileId plus page and bounding box for documents, or a timecode for audio. Set to false to skip grounding when you only need the values.
What one extraction result covers.
per_document— one result object per file (the default).across_documents— one result object for the whole set, read as a single body of evidence.rows_per_document— a list of results per file, for documents that hold repeated records.
Run a second review pass over the extracted values to catch mistakes. Slower and more thorough — worth it on documents where an error is expensive.
A single input file. Send this or files, never both.
Several input files, up to 100. Send this or file, never both.
Each file gets its own entry in output.documents[] unless unit says otherwise.
Arbitrary JSON you attach to the run and get back on every read of it.
Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.
Where to deliver this run’s events, given one of two ways.
{ "url": "…" }— a one-off https endpoint for this run only.{ "id": "whe_…" }— a saved endpoint fromPOST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.
Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.
How long, in seconds, to keep this run and its files before purging them automatically.
Defaults to 24 hours; the maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.
E-signature runs are exempt — an envelope waits for its signers however long that takes.
Response
Where the run is in its life.
The last four are terminal.
Why the run failed. Present whenever status is failed, and only then.
code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.
The human steps currently blocking the run. Present while status is needs_input.
Each task has a url — a ready-made page you can send a person to — or you can drive it yourself through GET and POST /v1/runs/{id}/task. E-signature runs never carry tasks[]: their signing links are signer-held secrets, so use envelopeUrl instead.
The output shape this run actually applied.
On an inference run — one sent with neither schema nor action — this is where you read the schema that was inferred, ready to review and save as an action for the next run.
The extracted data. Present once status is processed.
documents[] always has one entry per input file. For a single-document run, value and citations are lifted to the top as aliases of documents[0] so the common case reads without indexing.