PDF to Markdown API
One authenticated POST turns a public PDF URL into stored Markdown — with table merging, heading releveling, and page-range retrieval. Ready for pipelines and LLM ingestion.
- One REST Endpoint
- Conversion Options
- Paged Retrieval
- Structured Blocks And Markdown
- Idempotent Billable Writes
- Predictable Error Codes
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 Markdown API for document ingestion, RAG pipelines, and content migration — URL in, structured Markdown out.
One REST Endpoint
Call POST /v1/documents/parse with a bearer API key, a file_url, and a file_name. The API converts the document and returns a document_id — no browser automation or conversion cluster to host.
Conversion Options
Tune each parse: merge_tables merges fragmented table cells into coherent tables, relevel_titles normalizes heading hierarchy, and analysis_chart or recognize_seal handle specialized document features when you need them.
Paged Retrieval
Read results back through GET /v1/documents/{document_id} with page_start/page_end and markdown_start/markdown_end offsets. Long PDFs stay queryable instead of arriving as one unbounded string.
Structured Blocks And Markdown
The stored result carries both the full markdown field and structured blocks with page metadata — enough to build document search, chunking for RAG, or section-level citations.
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.
Predictable Error Codes
Handle failures with documented status codes: 400 for an invalid request, 401 for a missing or bad API key, 402 for insufficient balance, 409 for idempotency conflicts, and 502/503/504 for temporary upstream issues.
How to use
Follow these steps to call the PDF to Markdown API: create a key, submit the document URL, and read the stored Markdown 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) and file_name, plus any conversion options. The response returns a document_id and a preview of the conversion.
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 Markdown Back
Call GET /v1/documents/{document_id} with page and markdown offsets to fetch the stored result. Page ranges keep large documents navigable; markdown offsets slice the text precisely.
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, and 402 by topping up balance. Follow the documented Idempotency-Key behavior on 409. Retry 502/503/504 with backoff.
Frequently asked questions
What is the PDF to Markdown API?
An authenticated REST endpoint pair: POST /v1/documents/parse converts a public PDF URL into stored Markdown, and GET /v1/documents/{document_id} reads the result back with page ranges and markdown offsets. Conversion options include merge_tables and relevel_titles.
How does PDF to Markdown API pricing work?
Each parse is a metered operation that runs on your account's credits. Pricing is governed by the gateway rather than fixed numbers on this page — check the console for current costs, and use idempotency keys so retries never double-bill.
Can it convert local files?
No — the API accepts a public HTTPS file_url, not a multipart upload. Host the PDF where the API can reach it (object storage, a public bucket, your CDN) and pass that URL with the file_name.
How do I get the Markdown for a specific page range?
Call the read endpoint with page_start and page_end, or slice by character offsets with markdown_start and markdown_end. This keeps large documents queryable without fetching everything at once.
Does it handle tables and complex layout?
Tables come through as Markdown structure; enable merge_tables to merge fragmented table cells into coherent tables and relevel_titles to normalize heading hierarchy. Layout-only scans without a text layer are out of scope — no OCR promise.
How do I handle API errors?
Correct the request on 400, fix your bearer key on 401, resolve balance on 402, and follow the documented Idempotency-Key behavior on 409. Treat 502, 503, and 504 as temporary upstream failures and retry with backoff under the same key.