Documentation — PDF Central

Discovery

GET /api/v1/doctor
GET /api/v1/recipes
GET /api/v1/capabilities?view=summary&status=available
GET /openapi.json
GET /.well-known/agent-card.json
POST /mcp/core  # minimal profile
POST /mcp       # complete profile

Read a capability detail URL for its exact schema, scopes, limits, engine status, media types, and artifact types.

Authentication without login friction

Public discovery needs no credential. POST /api/v1/guest-sessions returns a restricted 30-minute bearer token. An idempotent upgrade issues one expiring developer-trial project API key with 10 MiB and 50 pages per file, two concurrent jobs, 24-hour retention, and monthly ceilings of 25 jobs, 250 pages, and 300000 microusd. Always read the returned limits; OAuth is only for delegated user access.

Idempotency and retries

Every state-changing write accepts Idempotency-Key. Reuse the same key after a timeout; changing the payload returns IDEMPOTENCY_CONFLICT. Honor Retry-After on HTTP 429 and inspect error.retryable.

Files and evidence

Create an upload, PUT raw bytes, and complete it with the staged ETag. Controlled URL import is limited to the configured HTTPS host allowlist: exact hosts or explicitly trusted vendor suffixes. Results remain private. Structured records retain source hashes and page evidence; receipts contain stable identifiers, price and engine versions, output hashes, and settlement state.

High-level recipes and compound workflows

Start with GET /api/v1/recipes. Submit POST /api/v1/process for read_document.v1, prepare_for_rag.v1, or extract_invoice.v1. Every accepted recipe returns the same durable job, artifact, evidence, and receipt lifecycle as a low-level operation.

GET /api/v1/doctor
GET /api/v1/recipes
POST /api/v1/process
Idempotency-Key: <stable-key>

{"recipe":"read_document.v1","source":{"file_id":"fil_..."},"ocr":"auto","execution":{"max_cost_microusd":100000}}

For larger agent tasks, use bounded batches, private document collections, version comparison, bundle classification, and versioned artifact corrections. Controlled URL import accepts HTTPS sources only from the operator-configured host allowlist: exact hosts or explicitly trusted vendor suffixes.

POST /api/v1/files/imports — controlled HTTPS PDF import
POST /api/v1/batches — at most ten tasks under one aggregate ceiling
/api/v1/collections — private indexing and retrieval
POST /api/v1/documents/compare — file, hash, page and quote evidence for text changes; geometry unavailable
POST /api/v1/document-bundles/classify — reviewable boundary proposals; create_files:true creates private child PDFs with page lineage
POST /api/v1/reviews — auditable structured corrections

Client libraries and workflow

Operational limits

GET /api/v1/limits is authoritative for the current period and credential. Check remaining jobs, pages, cost, and concurrency before scheduling a batch.

Read the agent FAQ