API documentation

Quick start

Send a file with a preset (or your own JSON schema) and get JSON back: every field of the schema is present, and a value that is not in the document is null.

curl -s $SCHEMALENS_URL/api/v1/extract \
  -H "Authorization: Bearer $SCHEMALENS_KEY" \
  -F file=@invoice.jpg \
  -F preset=invoice

{
  "data": {
    "invoice_number": "INV/12/2026",
    "issue_date": "2026-10-03",
    "seller_name": "Example Trading Ltd",
    "gross_total": 1200.0
  },
  "fields": {
    "gross_total": { "confidence": 0.93, "evidence": ["L011"] }
  },
  "usage": { "pages": 1, "ocr_ms": 2310, "llm_ms": 640, "language": "en" }
}

Endpoints

Extraction

POST /api/v1/extract takes a JPEG, PNG, WEBP, TIFF or PDF with printed text, up to MAX_UPLOAD_BYTES (4 MB by default) and MAX_PAGES (3) - both set in your .env.

Request (multipart)

curl -s -H "Authorization: Bearer $SCHEMALENS_KEY" $SCHEMALENS_URL/api/v1/extract \
  -F file=@invoice.pdf \
  -F 'schema={"type":"object","properties":{
        "seller_name":{"type":"string","description":"Name of the seller"},
        "issue_date":{"type":"string","format":"date"},
        "total_gross":{"type":"number"},
        "seller_nip":{"type":"string","x-schemalens-type":"nip"},
        "cost_category":{"type":"string","enum":["fuel","services","other"],
                         "x-schemalens-derived":true}}}' \
  -F 'options={"model_tier":"accurate","include_ocr_text":true}'

The same as JSON, with the document in base64:

curl -s -H "Authorization: Bearer $SCHEMALENS_KEY" $SCHEMALENS_URL/api/v1/extract -H "Content-Type: application/json" \
  -d "{\"document_base64\": \"$(base64 < receipt.jpg | tr -d '\n')\", \"preset\": \"receipt\"}"

Response

{
  "data": { "invoice_number": "INV/12/2026", "issue_date": "2026-10-03", "gross_total": 1230.0 },
  "fields": { "gross_total": { "confidence": 0.93, "evidence": ["L011"] } },
  "warnings": ["issue_date: normalized '03.10.2026' to '2026-10-03'"],
  "usage": { "pages": 1, "ocr_ms": 2310, "llm_ms": 640, "model": "openai/gpt-oss-20b",
             "language": "en", "ocr_confidence": 0.84, "context": "full" },
  "ocr_text": ["[L001] INVOICE No. INV/12/2026"]
}

Live progress

With ?stream=true the answer is NDJSON: one event per line while the document is processed. Events carry counts and timings, never the document's text.

curl -sN -H "Authorization: Bearer $SCHEMALENS_KEY" "$SCHEMALENS_URL/api/v1/extract?stream=true" -F file=@card.jpg -F preset=business_card

{"event": "accepted", "bytes": 111156, "pages": 1}
{"event": "reading", "pages": 1}
{"event": "read", "lines": 24, "ocr_ms": 3538, "ocr_confidence": 0.778, "language": "en"}
{"event": "extracting", "model": "openai/gpt-oss-20b", "fields": 9}
{"event": "result", "result": { "data": {}, "fields": {}, "warnings": [], "usage": {} }}

The last event is result (the usual JSON body) or error (the same problem a plain request would get). Errors found before the work starts come as plain responses.

Schemas and presets

Send a preset, your own schema, or both. With both, the schema extends the preset:

{ "preset": "business_card",
  "schema": { "type": "object", "properties": {
      "industry": { "type": "string", "x-schemalens-derived": true } } } }

Limits: up to 50 fields and 3 levels; types string, number, integer, boolean, array, object and enum; formats date, date-time and email. Every field is optional for the model: missing data is null, never a guess.

Extensions

Presets

Ready-made schemas with English field names; the documents can be in any language. GET /api/v1/presets lists their fields.

invoicereceiptcvbusiness_cardcontract_termsproduct_labelmenugeneric_documentlecture_notes

Result formats

curl -s -H "Authorization: Bearer $SCHEMALENS_KEY" "$SCHEMALENS_URL/api/v1/extract?format=xlsx" -F file=@invoice.jpg -F preset=invoice -o invoice.xlsx
curl -s -H "Authorization: Bearer $SCHEMALENS_KEY" "$SCHEMALENS_URL/api/v1/extract?format=csv&include_meta=true" -F file=@invoice.jpg -F preset=invoice -o invoice.csv

curl -s -H "Authorization: Bearer $SCHEMALENS_KEY" "$SCHEMALENS_URL/api/v1/render?format=xlsx" -H "Content-Type: application/json" \
  -d '{"result": { ... }, "preset": "invoice", "labels": {"gross_total": "Gross total"}}' -o result.xlsx

Errors

Errors are application/problem+json (RFC 9457). The type of a problem links to its row below (…/docs#error-invalid-schema): match on the slug at its end, not on the title. Every response has an X-Request-ID.

Run it yourself

The engine and the API are open source (Apache 2.0). In Docker on your machine - fully offline with a local model in Ollama - or on AWS with one command.

Docker

git clone https://github.com/maszjan/schemalens
cd schemalens && cp .env.example .env
uv run schemalens-api keys new --env-file .env   # prints your key, adds it to API_KEYS
docker compose up --build        # http://localhost:8000/docs

AWS

cd infra
sam build --use-buildkit && sam deploy --guided

Behind a reverse proxy

Paths start with /v1, the API's own version, as on a dedicated address (api.example.com/api/v1/extract). Behind a reverse proxy that serves it under a prefix, set ROOT_PATH=/api for example.com/api/v1/extract; the interactive docs and the OpenAPI servers follow it.

Configuration, presets, evals and the architecture are described in the repository.