Structured extraction

Two endpoints, same idea: you describe the shape you want as a JSON Schema, and the response is guaranteed to validate against it. You don't extract text yourself — OCR runs automatically wherever it's needed.

Use /documents/extract for a PDF (OCR only kicks in for scanned pages), and /images/extract for a loose image — a phone photo, a screenshot, a standalone scan — where every image goes through OCR.

Request#

Both take multipart/form-data with the same fields:

Example#

curl -X POST "https://api.trystac.com/v1/documents/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F file=@invoice.pdf \
  -F 'schema={
        "type": "object",
        "properties": {
          "invoice_number": {"type": "string"},
          "vendor_tax_id":  {"type": ["string", "null"]},
          "total":          {"type": "number"}
        },
        "required": ["invoice_number", "vendor_tax_id", "total"]
      }'

curl -X POST "https://api.trystac.com/v1/images/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F file=@invoice.jpg \
  -F 'schema={"type": "object", "properties": {"total": {"type": "number"}}, "required": ["total"]}'

Response#

{
  "data": { "invoice_number": "12345", "vendor_tax_id": "11-2223334", "total": 1500.0 },
  "pages": 3,
  "files": 1,
  "ocr_used": false,
  "usage": { "prompt_tokens": 2104, "completion_tokens": 48 }
}

The most important rule: mark fields nullable if they can be missing#

Output is grammar-constrained to match your schema token by token — that's what guarantees valid JSON, but it has a consequence that decides the quality of your results:

Declare any field that might legitimately be absent as nullable:

"vendor_tax_id": { "type": ["string", "null"] }

There's a second trap in the opposite direction: a field left out of required is optional under JSON Schema, so the model can simply omit the key instead of looking for the value — you get a 200 with valid JSON and a missing field, no warning. The combination that avoids both traps is required on every field, with nullable types on the ones that can legitimately be missing:

{
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "vendor_tax_id":  { "type": ["string", "null"] },
    "total":          { "type": "number" }
  },
  "required": ["invoice_number", "vendor_tax_id", "total"]
}

This applies inside nested arrays and objects too — each object in a list needs its own required, or items come back with fields silently missing.

Several files in one request#

When the fields you want are spread across documents — the invoice and the receipt, the contract and its amendment — send them all in one request through files and get one JSON back. Available from Pro.

curl -X POST "https://api.trystac.com/v1/documents/extract" \
  -H "Authorization: Bearer $STAC_API_KEY" \
  -F files=@invoice.pdf \
  -F files=@receipt.pdf \
  -F 'schema={
        "type": "object",
        "properties": {
          "invoice_number": {"type": "string"},
          "amount_paid":    {"type": ["number", "null"]}
        },
        "required": ["invoice_number", "amount_paid"]
      }' \
  -F 'user=The invoice number is on the invoice; the amount paid is on the receipt.'

Each file reaches the model in its own numbered block, labeled with the file name (--- DOCUMENTO 1 DE 2 (invoice.pdf) ---), so user can say where to look for each field.

• Go accepts 1 file per request. A second file — in files, or by repeating file — returns 413 with a message saying so. For several documents on Go, send one request per file.
• Plan limits apply to the sum. File size and page count are added up across all files in the request, and the request is rejected before any OCR runs.
• An empty document aborts the whole request (400, naming the file). Continuing without it would let the model fill the schema from the other files with no way for you to know.
• Want one JSON per file? Keep sending one request per file — multi-file is for fields that live in different documents.

Errors#

A truncated raw_output on a 502 usually means the response didn't fit the remaining context — the file is large and little room was left for the JSON. Split the PDF or trim the schema.

Limits#

Schema up to 64 KB on both. Server timeout: 240s — set your client's timeout above that; a multi-page scanned document can take minutes.