PDF to JSON API
One authenticated POST turns a public PDF URL into stored structured JSON — typed blocks, page text, and markdown, readable back by page range.
- One REST Endpoint
- Typed Block Schema
- Dual-Shape Output
- Paged Retrieval
- Idempotent Billable Writes
- Conversion Options
Request examples
curl -X POST "https://api.agentbody.io/v1/documents/parse" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"analysis_chart":"true","file_name":"YOUR_FILE_NAME","file_url":"YOUR_FILE_URL","merge_tables":"true","recognize_seal":"true","relevel_titles":"true","return_span_boxes":"true"}'Response examples
Documented responses from the OpenAPI specification.
Accepted document parse result reference.
{
"document_id": "00000000-0000-4000-8000-000000000001",
"get_path": "example_value",
"pages": 1,
"preview": "example_value"
}Features
Use the PDF to JSON API for data extraction pipelines, document indexing, and LLM ingestion — URL in, structured blocks out.
One REST Endpoint
Call POST /v1/documents/parse with a bearer API key, a file_url, and a file_name. The API parses the document and stores a structured result — no parsing library to host, no layout engine to maintain.
Typed Block Schema
Each block in the result carries id, type, text, page, and bbox — a stable, documented schema. Headings, paragraphs, and other elements arrive labeled, so downstream code routes them without guessing.
Dual-Shape Output
The stored result carries both the blocks array for programmatic use and a markdown rendering for reading and prompts — one parse serves your extraction pipeline and your LLM context from the same document_id.
Paged Retrieval
Read results through GET /v1/documents/{document_id} with page_start/page_end ranges. Thousand-page documents stay queryable; your worker walks them in chunks instead of one unbounded response.
Idempotent Billable Writes
Parsing is metered. Send an Idempotency-Key header on retries so an interrupted response does not double-bill the same document — repeated identical requests with one key return the original result.
Conversion Options
Tune each parse: merge_tables merges fragmented table cells into coherent tables, relevel_titles normalizes heading hierarchy — the same options that shape the markdown also shape the block structure.
How to use
Follow these steps to call the PDF to JSON API: create a key, submit the document URL, and read the structured blocks back.
Create An API Key
Create an AgentBody account and generate an API key in the console. Keep the key server-side and send it as a bearer token — never in browser code or client bundles.
Submit The Document
Send POST /v1/documents/parse with file_url (public HTTPS), file_name, and any conversion options. The response returns a document_id with a preview.
Add An Idempotency Key
Attach an Idempotency-Key header to every parse you might retry — timeouts, connection drops, worker restarts. Repeated identical requests with the same key return the original result without re-billing.
Read The Blocks Back
Call GET /v1/documents/{document_id} with page ranges. Parse the blocks array — id, type, text, page, bbox — straight into your storage, index, or pipeline.
Keep The Key Server-Side
Call the endpoints from your backend or a scheduled job. If users trigger conversions, proxy through your own endpoint so the key and billing stay under your control.
Handle Errors Correctly
Fix 400 by correcting the request, 401 by configuring a valid key, 402 by topping up balance, and follow the documented Idempotency-Key behavior on 409. Retry 502/503/504 with backoff.
Frequently asked questions
What is the PDF to JSON API?
An authenticated endpoint pair: POST /v1/documents/parse converts a public PDF URL into a stored structured result, and GET /v1/documents/{document_id} reads it back — a blocks array with id, type, text, page, and bbox per element, plus per-page text and markdown.
How does PDF to JSON API pricing work?
Each parse is a metered operation on your account's credits. Pricing is gateway-governed — check the console for current costs, and use idempotency keys so retries never double-bill.
What's in each JSON block?
Five fields: id (stable element identifier), type (heading, paragraph, and other element classes), text (the content), page (page number), and bbox (position on the page as coordinates). Enough to reconstruct or query the document's structure.
Can it process local files?
No — the API accepts a public HTTPS file_url, not multipart uploads. Host the PDF where the API can reach it (object storage, a public bucket) and pass that URL.
How do I handle very large PDFs?
Parse once, then read back with page_start and page_end ranges. Each retrieval returns a bounded slice of the blocks and pages, so thousand-page documents process in chunks without unbounded memory.
How do I handle API errors?
Correct the request on 400, fix the bearer key on 401, resolve balance on 402, and follow the documented Idempotency-Key behavior on 409. Treat 502/503/504 as temporary upstream failures and retry with backoff under the same key.