USE THIS WHEN you need specific values OUT of a document — a payslip's gross/net, an invoice's
total/ABN, a form's checkboxes, a table's cells — rather than a yes/no about the document. (For
"is this genuine?" use verify_document; "what kind of document is this?" is
`options={"classify": true}` right here.)

Say WHAT to pull, four ways:
  - `fields`: an ad-hoc list — names like ["gross_pay","abn"], or objects
    {"name":..., "type":"text|amount|date|boolean", "description":...}. THE general case: ask
    for exactly the fields your task needs. Use type "boolean" for a checkbox/tickbox.
    `"question"` works instead of `"description"` if you would rather just ask:
    {"name":"customer_name", "question":"What is the customer name?"}.
  - `template`: a named preset — "payslip", "tax_invoice", "bank_statement", "receipt".
  - NEITHER: AUTO — the document is classified and that type's fields are used.
  - auto on an unrecognised type: schema-free — every labelled field is returned.

Provide the document ONE way: `url` (a public http(s) link — fetched server-side, the cheapest
call) OR `bytes_b64` (inline base64, plus `filename` for PDF-vs-image routing). `country` is an
optional hint; `max_pages` caps how many pages are read (default a few; hard ceiling 10).

`options` turns on extra capabilities. Every one defaults OFF, and asking for one that this
server does not support is an ERROR naming it — never a silent no-op, so you can always tell
"asked wrongly" from "nothing found". Available today:
  - `{"grounding": true}` — every value gains `bbox` (the rectangle it was read from, in PDF
    points, origin top-left) and `text_layer_match`. Use it to CITE a value back to the page.
    Born-digital PDFs only for now; a scan returns `bbox: null` and `grounding: "none"`.
  - `{"flag_below": 0.7}` — adds `needs_review`, the fields under that confidence, weakest
    first. Use it to route the doubtful ones to a human instead of checking everything.
  - `{"tables": true}` — adds `tables`: whole tables with their rows. On a PDF these are
    read from the document's own rules and coordinates (exact cells, merged-cell colspans,
    no model call and NO CREDIT for the table pass); on a scan the model reads the rows and
    the table says `source: "vlm"` with no cell geometry. `{"tables": {"formats":
    ["json","markdown","html"], "borderless": true, "cells": true}}` to tune it.
  - `{"classify": true}` — adds `classification`: the full verdict (type, country,
    confidence, evidence), not just the routing. Free in auto mode.
  - `{"redact": true}` — adds `pii` (a MASKED inventory) and `redacted_text`, so you can
    extract and check for personal data in ONE call. A field you NAMED is still returned in
    full; the inventory never is. Two things to know before turning it on: `redacted_text`
    is the document's WHOLE text body with detected PII replaced — for a PDF that means
    every page, not just the ones `max_pages` covers — and redaction is best-effort
    coverage, so anything it failed to detect stays in that text verbatim. It also costs
    an extra page-equivalent per page, because it is a second model pass.
  - `{"layout": true}` — adds `layout.blocks`: every text block with its role
    (heading/body), font, size, column and reading order. Born-digital PDFs only; free.
  - `{"links": true}` — adds `links`: the PDF's own link annotations with uri, anchor
    text and bbox. Free. A URL merely PRINTED on the page is not an annotation.
  - `{"figures": true}` — adds `figures`: where the embedded images sit (bbox and pixel
    size), never the bytes. Free.
  - `{"chunks": true}` — adds `chunks`: retrieval-ready pieces that carry provenance a
    text splitter cannot give you — `heading_path` (where in the document), `bbox` and
    page range (citable back to the page), tables never sliced. Six strategies via
    `{"chunks": {"strategy": "section|page|chars|recursive|element|hierarchical",
    "max_chars": 1500, "min_chars": 200, "overlap": 100, "include_headings": true}}`.
    `hierarchical` adds parent context chunks for small-to-big retrieval. Born-digital
    PDFs only; free.
  - `{"split": true}` — adds `documents`: the page ranges of the distinct documents in
    one file (a bundle of 3 stapled PDFs -> 3 entries with types). One classifier call
    per page, so it costs +1 page-equivalent per page read.
`render_scale` (one of 1.0, 1.5, 2.0, 3.0, 4.0; default 2.0) raises rasterisation for small or
dense print. Call `GET /v1/extract/capabilities` for the full machine-readable list.

COST: 1 credit per page read, minimum 1 — with `fields` or a `template` given, a one-page
receipt costs 1 and a ten-page statement costs 10; AUTO mode adds 1 for the routing
classification. Options that add model reads add page-equivalents (`redact` +pages, `split`
+pages replacing the auto/classify +1, `tables` +pages only on a scan); deterministic work
is free, and an encrypted PDF is charged the one-page floor only. Pages charged is
min(`max_pages`, the document's real length), resolved before the call runs, so you can
predict the price. Set `max_pages` to cap your spend on a long document.
CAPABILITY-ONLY: `options.classify` and/or `options.redact` with no `fields`, no
`template` and no other option skips field extraction entirely — classify-only costs
1 credit and redact-only 1 per page, exactly what the retired classify_document and
redact_pii tools charged.

Returns `{mode, document_type, fields{name:{value,confidence,page}}, not_found, pages_read,
page_limit, page_count}`. `page_count` is the document's real length, so you can see when
`max_pages` truncated it. EXTRACTION, not verification — values are what the document SHOWS,
not proof it is genuine. A field that isn't clearly present comes back in `not_found` (it
abstains rather than guessing).

`text_layer_match` is `exact` / `normalised` when the printed value was located on the page,
`multiple` when the same string appears more than once (no box — we will not guess which), and
`absent` when it is not there. It reports whether the string was FOUND, not that the value is
correct. The document is never stored.