Extract
PDF to JSON extract API. Sync document processing modes, optional prompts, and response fields.
Endpoints
| Method | Path | Notes |
|---|---|---|
POST | /extract | Sync extract (mode=extract, engine=auto) |
POST | /upload | Full pipeline with optional mode / engine |
Content-Type: multipart/form-data. PDF only; max 10 MB and 100 pages. Password-protected PDFs return 400 PASSWORD_PROTECTED_PDF (they are not sent to Llama).
Form fields
| Field | Default | Description |
|---|---|---|
file | required | PDF upload |
extract_tier | plus | lite | plus | pro | ultra (aliases accepted) |
custom_fields | n/a | JSON string: [{ "name", "description", "type" }] |
system_prompt / custom_prompt | n/a | Optional. Either works; omitted cloud runs use a server default |
extract_schema | n/a | JSON Schema object as string. Highest priority when present |
schema_id | n/a | UUID of a saved org schema (GET/POST /org/schemas). Used when extract_schema is omitted |
save_schema_name | n/a | Optional name when Auto generate is persisted (title or generated if omitted) |
schema_type | auto | Classification hint. Auto is not a stable JSON contract (see below) |
engine | auto | /upload only |
cite_sources | false | Citations when supported |
confidence_scores | false | Confidence metadata |
target_pages / max_pages | n/a | Page limits |
do_not_cache | true | Prefer true for private docs |
Schema choice, first match wins: inline extract_schema > schema_id > custom_fields > canned schema_type (invoice, bill_of_lading) > Auto generate.
Header: Idempotency-Key (see Idempotency). Same key + org within 24h returns the first result with no second charge.
Auto is not a stable contract
schema_type=auto (the default) generates a JSON schema from the PDF. Field names can change between documents and over time. Do not hard-code Auto keys in an integration.
After the first Auto run:
- Read
schema_idon the extract response (DocAI also upserts a named schema for the org). - Pin
schema_idon later extracts (orGET /org/schemasand pick an id).
| Method | Path | Notes |
|---|---|---|
GET | /org/schemas | List saved schemas |
POST | /org/schemas | { "name", "schema_json" } upsert by name; version bumps when JSON changes |
GET | /org/schemas/{schema_id} | Fetch one |
PATCH | /org/schemas/{schema_id} | Update name and/or JSON |
DELETE | /org/schemas/{schema_id} | Delete |
Modes and credit burn
| Mode | Credits / page | Prompt / fields |
|---|---|---|
| Lite | 0.5 | Optional (auto-discover when omitted) |
| Plus | 2.0 | Optional (server default prompt if omitted) |
| Pro | 3.0 | Optional (server default prompt if omitted) |
| Ultra | 8.0 | Optional (server default prompt if omitted) |
Cost: round(pages × credits_per_page, 2). Insufficient balance returns 402 (see Errors). For Plus / Pro / Ultra, omitting system_prompt / custom_prompt uses an internal “extract everything” default; a caller prompt always wins when provided. Custom fields and extract_schema remain optional enhancers.
Example (Lite)
curl -X POST "$API/api/v1/extract" \
-H "Authorization: Bearer docai_sk_live_..." \
-F "file=@doc.pdf" \
-F "extract_tier=lite"Example (Pro without prompt)
curl -X POST "$API/api/v1/extract" \
-H "Authorization: Bearer docai_sk_live_..." \
-F "file=@invoice.pdf" \
-F "extract_tier=pro"Example (Pro with fields)
curl -X POST "$API/api/v1/extract" \
-H "Authorization: Bearer docai_sk_live_..." \
-F "file=@invoice.pdf" \
-F "extract_tier=pro" \
-F 'custom_fields=[{"name":"vendor","description":"Supplier name","type":"string"},{"name":"total","description":"Invoice total","type":"number"}]'Response (summary)
Successful responses include document_id, filename, status, page_count, mode, confidence_score, extracted_json, optional schema_id, citations / extract_metadata, and review flags (requires_human_review, missing_fields).
If retention is off, sensitive payloads may be omitted from later history. See trust settings in the product UI.