Documentation

Everything you need to go from a folder of PDFs to validated JSON. SDK version 2.3.0, API version 2026-02-01.

Quickstart

Install the SDK, grab an API key from the dashboard, and parse your first document in under two minutes:

$ pip install unstructred
$ export UNSTRUCTRED_API_KEY="us_live_..."

from unstructred import Client

client = Client()  # picks up UNSTRUCTRED_API_KEY

doc = client.parse(
    "invoice_2026_0142.pdf",
    schema="invoice",   # or a schema id from your workspace
)

print(doc.fields.invoice_number)   # 'INV-2026-0142'
print(doc.fields.total.gross)     # 4980.00
print(doc.fields.total.currency)   # 'EUR'
print(doc.confidence)               # 0.97

Authentication

API keys are prefixed us_live_ (production) or us_test_ (sandbox). The SDK reads UNSTRUCTRED_API_KEY; over raw HTTP send it as a bearer token:

curl https://api.unstructred.io/v1/parse \
  -H "Authorization: Bearer $UNSTRUCTRED_API_KEY" \
  -F "file=@invoice_2026_0142.pdf" \
  -F "schema=invoice"

Python SDK

The SDK is synchronous by default with an async twin (AsyncClient). Pipelines — watchers, sinks and retries — are configured in a pipeline.yaml or in code:

from unstructred import Pipeline

pipe = Pipeline.from_file("pipeline.yaml")
pipe.run(source="s3://acme-inbox/", sink="webhook:https://erp.acme.dev/hooks")

Schemas

Schemas define what to extract and how to validate it. Fields are typed, can be nested, and every extracted value carries a confidence score between 0 and 1:

schema: invoice
version: 3
fields:
  invoice_number: { type: string, pattern: "INV-\\d{4}-\\d{4}" }
  issue_date:     { type: date,   format: "%Y-%m-%d" }
  vendor:
    name:    { type: string }
    vat_id:  { type: string, pattern: "DE\\d{9}" }
  total:
    gross:    { type: decimal }
    currency: { type: enum, values: [EUR, USD, GBP] }
tables:
  line_items:
    columns: [description, qty, unit_price, tax_rate]
    min_rows: 1

REST API

Method	Path	Description
`POST`	`/v1/parse`	Parse one document (multipart or URL)
`GET`	`/v1/documents/{id}`	Fetch result + provenance
`POST`	`/v1/batches`	Batch up to 10,000 documents
`POST`	`/v1/schemas`	Create or update a schema
`POST`	`/v1/webhooks`	Register a result webhook

Parse results include per-field bounding boxes and page numbers, so your frontend can highlight the source of every value.

Rate limits & quotas

Plan	Pages / month	Concurrent parses
Free	1,000	2
Scale	500,000	50
Enterprise	custom	custom

Requests return 429 with a Retry-After header when concurrency limits are hit. Batch submissions queue with no practical limit.

Files up to 200 MB and 2,000 pages are accepted. Anything larger should be split client-side — trust us, your downstream systems will thank you too.

Errors

HTTP	Code	Meaning
400	`invalid_schema`	Schema failed validation
401	`invalid_api_key`	Unknown or revoked key
413	`file_too_large`	Over 200 MB / 2,000 pages
415	`unsupported_type`	Not a supported document format
422	`extraction_failed`	No fields matched above threshold
429	`rate_limited`	Concurrency or quota exceeded

Pricing

Free tier includes 1,000 pages a month forever. Paid plans are per page with volume discounts — the first 1,000 pages are on us so you can benchmark on your real documents. Current customers range from two-person fintechs to public-sector archives processing 4M pages a month. Full tiers, per-page rates and the FAQ live on the pricing page.

Stuck? Email support@unstructred.io — we answer fast, and schema questions are our favorite kind.