Document extraction
Attach PDFs, images and emails to a run, let Claude fill a schema you declare — every field with a confidence and the page it was read from — and have a person review the uncertain fields at a gate, side by side with the document, before any step uses them.
A run can carry documents: a supplier invoice, a scanned claim form, an email with its
attachments. An agent step that declares an extract block sends them to Claude and
asks for the fields of a schema you declare. Every field comes back with a confidence and a
citation — the document, the page and a short quote — and the fields under their
threshold are flagged. A gate that reviews the extraction shows the documents beside the
fields; what the reviewer signs replaces what the model read, and the steps after the gate read
the reviewed values.
The product rule holds: a model proposes, a person disposes. An uncertain value never flows on silently — it waits for a person, at the reviewing gate or at the extraction step itself.
Attach documents
| Where | How |
|---|---|
| At the start, in the browser | Runs → pick the process → Documents (optional) → Start run. |
| At the start, over the API | POST /process-runs with documents: [{name, content_base64, label?}] (at most 10). |
| From a webhook trigger | The JSON body's reserved field _documents (same shape) — attached, never copied into the inputs. Raise TRIGGER_WEBHOOK_MAX_BYTES for real files. |
| While the run waits at a gate | The sign-off card's Attach a document, or POST /process-runs/{id}/documents?name=…&label=… with the raw file as the body. |
A label (invoice, contract) lets an extraction step read only the documents it is about.
The documents of a run: GET /process-runs/{id}/documents; one document's bytes:
GET /process-runs/{id}/documents/{doc}/content.
What is accepted, and how it is checked. The type is decided by the file's first bytes —
never by its name or the Content-Type the sender claims: a .pdf that starts like a PNG is
stored as the PNG it is, and anything that is not one of the types below is refused (415).
| Type | Handling |
|---|---|
pypdf opens it only to count its pages. Scripts, actions, forms and embedded files are never looked at or run. A password-protected PDF is refused. | |
| PNG, JPEG, WebP | Pillow checks it is an image of a sane size (decompression bombs refused). At most 5 MiB — the model's image limit. |
| TIFF | Claude does not read TIFF: Pillow re-encodes it into a PDF, one page per frame (converted_from: image/tiff). |
Email (.eml) | Stored as its text (headers and body; an HTML-only body is reduced to text). Each PDF/image attachment becomes a document of its own (parent_id = the email); other attachments are skipped and named in the answer. |
A document is served back as the type it was sniffed as, with X-Content-Type-Options: nosniff
and a sandbox Content-Security-Policy, so a file that is also HTML (a polyglot) never runs in
a browser.
Limits (environment of the API):
| Variable | Default | |
|---|---|---|
DOCUMENT_MAX_BYTES | 10 MiB | per file (413) |
DOCUMENT_MAX_IMAGE_BYTES | 5 MiB | per image (413) |
DOCUMENT_MAX_PAGES | 100 | per PDF or TIFF (422) |
DOCUMENT_MAX_PER_RUN | 10 | documents on one run (409) |
DOCUMENT_MAX_RUN_BYTES | 20 MiB | all of a run's documents together, so one extraction stays under the API's 32 MB request (413) |
DOCUMENT_MAX_ATTACHMENTS | 10 | attachments taken from one email |
Storage. Postgres, table run_documents. Each file is encrypted with AES-256-GCM under a key
of its own (the document id and company bound in as associated data); that key is sealed by the
same secret box as every stored credential (MINCTRL_SECRETS_KEY). A database backup holds
ciphertext only. Deleting the run deletes its documents.
Permissions. A person needs documents.upload to attach (and runs.start, as the route
starts-and-feeds runs) and documents.read to see and open a run's documents. Every
built-in role holds both; a custom role can leave them out. An API key attaches with its
runs:start scope and reads with runs:read.
Audit. Every attachment is a document_attached entry: the stage (start or gate), who, and
per document its id, kind, type, size, pages and SHA-256 — never its name or content (a file
name can be a patient's name).
Declare the extraction
On an agent node:
{
"id": "read",
"kind": "agent",
"label": "Read the invoice",
"agent": "clerk",
"tools": [],
"tier": "low",
"extract": {
"schema": {
"type": "object",
"properties": {
"invoice_no": { "type": "string", "title": "Invoice number", "description": "The supplier's invoice number" },
"total": { "type": "number", "description": "The total amount due, as a plain number" },
"currency": { "type": "string", "enum": ["EUR", "USD"], "description": "The currency of the total" },
"due": { "type": "string", "format": "date", "description": "The payment due date" }
},
"required": ["invoice_no", "total", "currency"]
},
"order": ["invoice_no", "total", "currency", "due"],
"instructions": "Read the supplier invoice. The total is the amount after tax.",
"documents": "invoice",
"threshold": 0.8,
"field_thresholds": { "total": 0.95 },
"model": "claude-sonnet-5-5"
}
}| Key | Meaning |
|---|---|
schema | A JSON Schema object; its properties are the fields (at most 20). Each field needs a description — what the model looks for — and is a string (optionally enum, format: "date", pattern, minLength/maxLength), a number or integer (optionally minimum/maximum) or a boolean. required fields must be found. |
order | The order people see the fields in (a stored graph does not keep an object's key order). Left out: the required fields in their order, then the rest by name. |
instructions | Optional guidance, at most 10,000 characters. |
documents | A label: read only the run's documents with it. Left out: every document of the run. |
threshold | The confidence (0–1) under which a field is flagged. Default 0.8. |
field_thresholds | Per field, overriding threshold. |
model, max_tokens | As for LLM agent steps. |
What the model receives. Each document as Claude's native input — a PDF as a document
block, an image as an image block, an email's text as a plain-text document block — each
introduced by its number and name, then your instructions and the field list. The system
prompt tells the model that the documents are data, not instructions. The answer is
constrained (structured outputs) to, per field: value (or null), confidence, document,
page, quote.
What is checked here. The values against your full schema (required fields, types, enums,
bounds, patterns, dates as YYYY-MM-DD); every citation against the real page count of the
document it names; every confidence in 0–1. A broken answer is sent back once with what is
wrong; a second broken answer fails the step (llm_schema). A required field the documents do
not contain therefore fails the step instead of being guessed.
What is flagged. A field whose confidence is under its threshold, a field not found (optional fields only — a missing required one fails the check), or a value without a page.
Run state. extracted.<step> (the values object), extracted.<step>.<field> (each value) and
extracted.<step>._flagged (the flagged field ids). Connector maps, decision tables and
gateways (route_on: "extracted.read.currency") read them like any other state. The run's trace
also carries extracted: each extraction step's values as the run stands, and whether a gate
reviewed them.
Without a reviewing gate, an extraction with flagged fields parks at its own step: a person looks at the documents and the fields on the sign-off card and approves (the model's values stand) or denies.
Review at a gate
A gate declares which extraction it reviews:
{ "id": "check", "kind": "gate", "label": "Check the invoice", "human": "ap_clerk",
"gate": "gate:check-invoice", "tier": "high", "review": "read" }The gate's form is derived from the extraction's schema — one field per extracted field (enum → select, date → date, number → number, boolean → checkbox, string → text) — so a review gate declares no form of its own. On the sign-off card the reviewer sees:
- the document viewer — the PDF in the browser's viewer at the cited page, the image, or the email's text; several documents as tabs; a document that cannot be opened says so, with a retry;
- the fields as the model read them, each with its confidence and citation; a click on a citation turns the viewer to that page;
- the form pre-filled with the model's values, the flagged fields highlighted with why.
The reviewer corrects what is wrong and signs. A field left as it was is signed as the model read it. The values go through the form check and the extraction schema (a whole number stays whole, a pattern holds) — a refused value is named under its field and nothing is signed. A review gate is always signed on its own card, never in bulk — and never from Slack, Teams or an embedded widget: they show "Open in Minctrl", and the sign door refuses a review signature from any channel but the sign-off card (409), so what a model read is settled only where the documents are shown. The same holds for an extraction step parked on its own flagged fields.
What the signature records:
- the reviewed values in the run's decisions — the steps after the gate read them as
extracted.<step>.<field>(andgate_form.<gate>.<field>), on this drive and on every replay; - the
gate_signedentry with the form values, as for any gate with a form; - an
extraction_reviewedentry: who reviewed, the verdict, each corrected field (the model's value, the reviewed value, its confidence, whether it was flagged) and the fields confirmed as they were.
A resume never asks the model again: the extraction's answer is in the trace and is replayed.
Cost, budgets and records
An extraction is a model call like any LLM step: it is checked against the company's monthly
budget and the per-run cap before it is made (reached → the step fails with "LLM budget
reached", nothing is sent), and each call is an llm_usage row and an llm_call audit entry
(model, prompt hash, tokens, cost, latency, output hash). Documents are large inputs — expect
the input tokens of a long PDF. When the company keeps model text, the kept prompt has every
document replaced by its id: the documents are stored once, encrypted, never in a call record.
PHI mode and retention
In PHI mode no prompt or output text is kept for any call.
The retention purge that empties a finished run's inputs deletes its documents in the same
transaction; its phi_inputs_purged entry counts them per run (documents, documents_removed)
and never names them. Opening a document is opening the run: while run views are logged, the
view is recorded before the document is served.
The same purge removes what the model read from those documents: in the run's trace every
extraction's values and quotes (and the documents' names), the run's extracted summary, a
branch reason that quoted an extracted value, and the values signed at a review gate (in the
trace, the decisions and the notes) — extracted_fields_redacted counts them per run. Field
ids, confidences, pages and flags stay: they say how the run was decided, not what the
documents said. What this does not reach: the gate_signed and extraction_reviewed audit
entries (the hash-linked chain is never rewritten), and a database backup taken before a purge,
which still holds the encrypted documents until it ages out.
Test suites
A test case replays an extraction from a recorded answer —
fixtures: {"read": {"extraction": {"fields": {...}}}}, the model's answer shape — checked and
flagged exactly as a live one, with no call and no document. Recording a case keeps each
extraction's answer as its fixture. Assertions read $.llm_output.<field> (the values) and
$.flagged[0].
Limits stated plainly
- Extraction runs on the default (replay) runtime, like LLM steps; the Temporal runtime does not run extraction steps.
- The viewer is the browser's own PDF viewer; a citation turns to its page but does not draw a box on it (the API returns pages and quotes, not coordinates).
- Handwriting and poor scans are read as well as the model reads them — that is what the confidence and the review are for.
LLM agent steps
Let Claude do an agent step's work — a structured answer checked against your schema, tool calls through your connectors, irreversible actions only proposed for a person to sign, every call recorded with its cost, and spend bounded by budgets.
Decision tables
Decide by rules inside a process — a DMN 1.3 decision table, versioned with the process, evaluated by a decision step, branched on by a gateway, with the matched rule in the trace and the audit chain.