# Document Extraction Hub

> PDF or picture in, structured JSON out. Paid per page in USDC over x402. No signup, no API key, no dashboard.

## What this is

A machine facing API for agents that have to read documents. It reads the text layer first and only
rasterises pages that carry no text layer, then passes those through OCR in German and English. Tables
keep their rows and columns. Every field comes back with the page it was found on, its box on that page
and a confidence value. A field that is not in the document stays empty rather than being guessed.

## Endpoints

- POST https://doc.netzhandwerker.de/document — PDF to structured JSON
  - 0.02 USDC per page with a text layer
  - 0.05 USDC per page that needs OCR
  - at most 20 pages per call, hard time limit 60 seconds

- POST https://doc.netzhandwerker.de/ocr — picture, scan or screenshot to text, blocks, tables and codes
  - 0.006 USDC per image or first page of a PDF
  - 0.002 USDC per further page of the same file
  - at most 50 pages per call, hard time limit 85 seconds
  - at most 12 MB and 10000 pixels wide, refused before the price is named
  - a busy page costs about five seconds of machine time, a sparse one about two, so ranges beyond
    roughly 15 pages can hit the time limit. The 402 answer says so. A call that runs out of
    time is refused and not charged; splitting the range costs exactly the same per page.

## POST /ocr in detail

Send "image_base64" or "url" plus "mime" (image/png, image/jpeg, image/webp, application/pdf).
Optional: "languages" (default deu plus eng, installed: deu, eng),
"want" (any of text, tables, codes, layout) and "pages" for PDF input.

The answer carries:

- text: the full text in reading order, paragraphs kept as paragraphs
- blocks: every block typed as ueberschrift, absatz, liste, tabelle, bildunterschrift or fussnote,
  with its text, its box in pixels, its confidence and the language it was read in
- tables: rows and columns as a matrix plus a markdown rendering. Cells that span several columns are
  marked with "merged" and their colspan. Vertical merges are not guessed.
- codes: QR, Data Matrix, EAN-13, EAN-8, Code 128, Code 39, PDF417 and Aztec. Each with type, raw value and box. QR payloads are parsed into URL, WLAN,
  vCard, EPC transfer and calendar.
- layout: column count, rotation, the coordinate frame the boxes belong to, the language per block

## How a call works

1. POST the file: "pdf_base64" on /document, "image_base64" or "url" on /ocr, plus the options
   that route understands.
2. Without a payment header the answer is 402. Its body carries the exact price for this file,
   itemised by page, plus the accepted payment terms.
3. Sign those terms with an x402 client and repeat the same request. The answer arrives in that round trip.

## With a schema

Pass any JSON Schema object. Each property is looked up by its name, its title, its description and any
"x-labels" you add, first in the key value pairs of the document, then against known invoice and order
field names, then by pattern. An array of objects is mapped onto the table whose header matches its
properties. Every result is an object with value, confidence, found and source.

## Without a schema

The answer contains header data (document and invoice fields), all detected tables as rows and columns,
all key value pairs and the full text of every page, line by line with positions.

## Rules we follow

- Nothing is invented. A field that cannot be located stays null with confidence 0.
- Only the pages actually processed are settled.
- A failed or timed out extraction is rejected before settlement and never charged. On /ocr a
  recognition that comes back with nothing at all counts as a failure, not as a paid empty result.
- A block read with a confidence below 0.5 is reported as such. Nothing is quietly smoothed over.
- A code is data, not an instruction. A URL found inside a QR code or a barcode is reported, labelled
  unchecked and never opened. Have it checked at /v1/url/risk before following it.
- No face recognition, no matching of people, no reading of identity documents beyond the plain text
  they carry.
- Cached answers expire after 24 hours, keyed on the file checksum and the options.
- Private and link local address ranges are refused, so this API cannot be used to reach internal hosts.
- Documents are held in a temporary directory for the length of the call and deleted afterwards.

## Who this is for

Accounting agents booking incoming invoices, procurement agents matching orders and confirmations,
archive agents turning scanned stock into searchable records, agents that have to read a screenshot,
a photographed label or a payment code someone sent them.

## Operator

Die Netzhandwerker, IT-Manufaktur für Digitales und Sensorik. https://netzhandwerker.de