Extraction · Extract

• Endpoint: POST /api/v1/render's sibling — POST https://inkrun.dev/api/v1/extract, authenticated with the same Authorization: Bearer sk_... key.
• MCP tool: extract — same contract, same envelope, available to any agent connected to the Inkrun MCP server.
• Recommended workflow: call Inspect first — it's free and tells you the page count, which pages are scanned, and exactly what each tier will cost for your document.

Request body (JSON)

Example — preset

curl "https://inkrun.dev/api/v1/extract" \
  -H "Authorization: Bearer $INKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"file_base64\": \"$(base64 -i invoice.pdf)\",
    \"preset\": \"invoice\"
  }"

Example — custom schema

curl "https://inkrun.dev/api/v1/extract" \
  -H "Authorization: Bearer $INKRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"file_base64\": \"$(base64 -i order.pdf)\",
    \"schema\": {
      \"type\": \"object\",
      \"properties\": {
        \"customer\": { \"type\": \"string\" },
        \"order_date\": { \"type\": \"string\", \"format\": \"date\" },
        \"total\": { \"type\": \"number\" }
      }
    }
  }"

Custom schemas are plain object schemas: $ref, allOf/anyOf/oneOf and other composition keywords are rejected by name, and size, depth and property count are capped (400 schema_too_complex). Field names double as label anchors in the document, so name them the way the document labels them — invoice_number, due_date, total. String fields with format: "date" parse as dates; number fields named total/amount/price parse as money.

Response — the envelope

{
  "id": "ext_9f2a4e1c",
  "data": {
    "vendor": "Acme Co",
    "invoice_number": "INV-2026-0042",
    "invoice_date": "2026-06-30",
    "due_date": null,
    "currency": "USD",
    "subtotal": 1130.00,
    "tax": 110.50,
    "total": 1240.50,
    "line_items": [
      { "description": "Consulting", "quantity": 10, "unit_price": 113.00, "amount": 1130.00 }
    ]
  },
  "fields": {
    "vendor":         { "confidence": 0.98, "method": "deterministic", "page": 1 },
    "invoice_number": { "confidence": 0.99, "method": "deterministic", "page": 1 },
    "invoice_date":   { "confidence": 0.97, "method": "deterministic", "page": 1 },
    "currency":       { "confidence": 0.95, "method": "deterministic", "page": 1 },
    "subtotal":       { "confidence": 0.98, "method": "deterministic", "page": 2 },
    "tax":            { "confidence": 0.98, "method": "deterministic", "page": 2 },
    "total":          { "confidence": 0.99, "method": "deterministic", "page": 2 },
    "line_items":     { "confidence": 0.93, "method": "deterministic", "page": 1 }
  },
  "extraction_method": "deterministic",
  "warnings": [
    "due_date could not be grounded in the document and was returned as null."
  ],
  "credits_charged": 1,
  "pages": 2,
  "size_bytes": 184220,
  "duration_ms": 412
}

Presets

A preset ships its own output schema and grounding rules — the fastest path for the common document types:

Extraction tiers & credits

Extraction escalates through up to three tiers, and you are only charged for the tier that actually ran:

• Deterministic — positioned-text rules over the document's text layer. Reproducible run-to-run, never leaves Inkrun's servers.
• Model — fields the rules couldn't ground are escalated to a model over the extracted text and layout (never your file bytes); returned values are verified against the document text before they're trusted.
• OCR — opt-in only (ocr_fallback: true), for scanned pages with no text layer. Because OCR reads pixels, its values can't be verified against extracted text: they are labelled method: "ocr" and their confidence is capped at 0.8. Refused above 15 scanned pages in one call (413).

Example: a 30-page digital invoice costs 2 credits on the deterministic tier (1 for the first 20 pages, +1 for the started next 20). A 5-page scan with ocr_fallback: true costs 10. Over-quota fails before any parsing with 429 quota_exceeded.

Errors

Same envelope as the render API: { "error": { "code", "message" } }, with x-request-id echoed on every response.

Machine-readable spec

This page is the human reference. A machine-readable OpenAPI spec for the v1 API (render and extraction together) is planned as its own piece of work and will be cross-linked here when it ships.