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,
  "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.

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.