Document parsing API
Send a PDF or image to Paddle, Mistral, Azure, Google, or AWS Textract. The parse API returns normalized elements, markdown, table structure, bounding boxes, and confidence when the selected model supports them.
Parse a PDF into text and layout
Send a PDF, PNG, or JPEG with your API key. This one-page response shows text, markdown, page geometry, and a source element.
curl https://api.openparser.dev/parse \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F 'request={"ocr_model":"paddleocr-vl-1.6","output_format":"openparser@1"};type=application/json' \
-F "file=@statement.pdf"{
"output_format": "openparser@1",
"document_id": "doc_3f9a2c",
"provenance": {
"provider": "paddle",
"model": "paddleocr-vl-1.6"
},
"text": "Total due: $4,318.20",
"markdown": "Total due: $4,318.20\n",
"pages": [
{
"number": 1,
"width": 1700,
"height": 2200,
"unit": "pixel",
"element_ids": [
"elem-total"
],
"reading_order": [
"elem-total"
]
}
],
"elements": [
{
"id": "elem-total",
"kind": "text",
"role": "paragraph",
"text": "Total due: $4,318.20",
"spans": [
{
"start": 0,
"end": 20
}
],
"locations": [
{
"page_number": 1,
"bbox": {
"left": 14,
"top": 53,
"right": 146,
"bottom": 123
}
}
],
"confidence": {
"score": 0.98,
"scope": "recognition",
"calibrated": false
}
}
],
"relations": [],
"text_annotations": [],
"assets": []
}Plan your document intake
Check upload limits and choose a job mode before you integrate.
| Item | What to expect |
|---|---|
| File formats | PDF, PNG, and JPEG. Convert office documents to PDF before uploading. |
| File size | Up to 50 MiB per source file. Encrypted PDFs are rejected. |
| Batch size | 1 to 100 documents per batch request. |
| Response time | Depends on the model, page count, and queue. No fixed latency is promised. |
| Synchronous requests | POST /parse can return 202 when its wait window expires. Poll the job URL in the Location header. |
| Asynchronous requests | POST /parse/async returns a job. Poll GET /jobs/{id} for status and results. |
| Model limits | Provider page limits and output capabilities vary. Check the model catalog before choosing an engine. |
Read the API quickstart for upload examples and the OCR model catalog for provider capabilities.
When should you use a document parsing API?
Choose an approach based on your source documents and the output you need.
- Local PDF text extraction
- Use a local text extractor when your PDFs already contain selectable text and you only need that text. Scan-only pages need OCR.
- Self-hosted OCR
- Run an open-weight model when you want to manage inference on your infrastructure. Budget for compute, queues, updates, and monitoring.
- Hosted document parsing
- Use OpenParser when you want OCR and layout through an API. Read text and markdown, inspect page elements, and switch models through the same request format.
- Structured field extraction
- If you need invoice totals or contract dates as JSON, use the document extraction API. Parsing returns document content; extraction fills your schema.
POST /parse returns typed layout elements
Call /parse, /parse/async, or /parse/batch. Poll /jobs for status. GET /files/{id}/content when you need the source bytes again.
/parserequestcurl https://api.openparser.dev/parse \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F 'request={"ocr_model":"paddleocr-vl-1.6","output_format":"openparser@1"};type=application/json' \
-F "file=@statement.pdf"{
"output_format": "openparser@1",
"document_id": "doc_3f9a2c",
"provenance": {
"provider": "paddle",
"model": "paddleocr-vl-1.6"
},
"text": "Total due: $4,318.20",
"markdown": "Total due: $4,318.20\n",
"pages": [
{
"number": 1,
"width": 1700,
"height": 2200,
"unit": "pixel",
"element_ids": [
"elem-total"
],
"reading_order": [
"elem-total"
]
}
],
"elements": [
{
"id": "elem-total",
"kind": "text",
"role": "paragraph",
"text": "Total due: $4,318.20",
"spans": [
{
"start": 0,
"end": 20
}
],
"locations": [
{
"page_number": 1,
"bbox": {
"left": 14,
"top": 53,
"right": 146,
"bottom": 123
}
}
],
"confidence": {
"score": 0.98,
"scope": "recognition",
"calibrated": false
}
}
],
"relations": [],
"text_annotations": [],
"assets": []
}Inspect parsed elements in the playground
Upload a PDF, review markdown and element kinds, then create API keys for POST /parse.
{ total: "$4,318.20" } b4ParsedDocument with pages and layout elements
POST /parse returns elements[], markdown, and stable fields your integration can rely on.
Typed layout elements
Each page references layout elements in reading order. Elements represent text, tables, figures, and signatures. Text roles distinguish headings from body content. Every element has an ID you can cite downstream.
OCR confidence
Elements can include OCR confidence scores. Set a threshold and send low-confidence results to review before they enter your pipeline.
Normalized output
Responses use one normalized contract: document_id, pages[], elements[], text, markdown, and stable fields for downstream processing.
Downstream extraction
Parsing stops at layout. Point /extract at a parse job when you need JSON against a schema, with citations tied to element IDs.
Bounding boxes
Element locations include page numbers and bounding boxes when the selected model supplies them. Highlight the region behind a citation or overlay parsed content on the original PDF.
Tables and figures
Tables return as structured elements with cells and optional HTML. Figures carry their own element type so agents can treat charts and images differently from body copy.
Parsing bills by page count
Each ocr_model publishes a page rate. /extract bills separately by llm_model token usage.
llm_model tokens- $10 credits at signup
- Open-weight hosted models from $1 per 1,000 pages
- Each
ocr_modelpublishes its own page rate - Sync, async, and batch included
- Extraction billed per token on the LLM you choose
- Console and API keys
Document parsing API FAQ
Nine ocr_model ids, ParsedDocument fields, sync/async/batch modes, and page pricing.
Which OCR models can the document parsing API run?
Choose from nine hosted models across Paddle, Mistral, Azure Document Intelligence, Google Document AI, and AWS Textract. Pass the model id in ocr_model on each parse request.
What does a parse response contain?
A ParsedDocument with output_format openparser@1, document_id, pages[], text, markdown, and elements[]. Elements can include text, headings, tables, figures, bounding boxes, and confidence values.
Can I parse PDFs asynchronously?
Yes. POST to /parse/async, then GET /jobs/{id} for status and the result when the job succeeds. Batch parsing uses /parse/batch with multiple files in one request.
How is parsing different from basic OCR?
Text-only OCR focuses on recognized text. Document parsing also represents layout and reading order. OpenParser returns text, markdown, pages, and elements. Table detail, geometry, and OCR confidence depend on the selected model.
How much does parsing cost?
New accounts get $10 in credits. Open-weight hosted models start at $1 per 1,000 pages; other OCR models publish their own per-page rates. Structured extraction adds the token cost of the language model you select.
What file types can I send?
PDF, PNG, and JPEG files up to 50 MiB. Encrypted PDFs are rejected. Convert office documents to PDF first, then upload as multipart form data alongside the request JSON.
Pick ocr_model and inspect elements before you integrate
Upload a PDF, set ocr_model, and review markdown, element kinds, and confidence scores in Studio before you call POST /parse.