extract_fields

sh.stipple/openwarrant · Verify this server

Extract structured FIELDS from a document (PDF or image) with a vision model. 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. Costs 1 credit(s) PER PAGE read (minimum 1) — cap a long document with max_pages.