What belongs in the JSON
Keep a stable id for the source, an ordered list of pages, and blocks that point at a page. A block can be a heading, a paragraph, a list, or a table. Optional boxes are included when the route actually measured them.
Leave a field out when the route cannot support it. A successful status does not mean every coordinate is known.
Markdown stays beside the JSON
People and models read Markdown. Applications that cite a page or rebuild a table read the JSON. Generating one and discarding the other forces the next step to guess.
Both come from the same job. The job also stores parser version, route, and warnings, so a later chunk can name the parse it came from.
Call the same endpoint
POST /v1/parse accepts a multipart file, raw bytes with x-filename, or a permitted HTTPS URL. wait=true returns the inline result for a short file. Longer work uses a job.
The response contract is the same idea either way: Markdown for the text, DocIR for the structure, and a manifest for the route.
A document shape you can validate
The container writes parserVersion cloudflare-docparse-container.0.2.0. Block ids start at b000001. Each block's pageIndex has to appear on a page, and that page's blockIds list has to include the block. A table block carries rows as arrays of strings.
metadata.route for a normal text-based PDF is container. A box is included when the path measured one, in points for a PDF page. Leave a coordinate out of your own copy when the block has no bbox, rather than filling zeros.
A container PDF also records metadata.engine, metadata.pdfPageCount, and metadata.pdfTextLayerFastPath. pdfPageCount is the number of pages in the file. pdfTextLayerFastPath is true when the digital text-layer path ran. Block types are heading, paragraph, list, table, formula, code, image, and unknown. The first block id is b000001, and later ids follow in order. A measured PDF box uses unit pt. A block with no measured box omits bbox. wait=true returns HTTP 200 with both artifacts. Without that flag the response is HTTP 202, and the JSON is read from the job links.
- schemaVersion is docir.v1.
- pages[].blockIds is the order to cite.
- A table cell lives in block.rows, not only in Markdown.
- metadata.warnings is part of a successful document.
{
"schemaVersion": "docir.v1",
"parserVersion": "cloudflare-docparse-container.0.2.0",
"metadata": { "route": "container", "warnings": [] },
"pages": [{ "index": 0, "blockIds": ["b000001"] }],
"blocks": [{ "id": "b000001", "type": "paragraph", "pageIndex": 0, "text": "Revenue by segment" }]
}
The file to send
Send one text-based PDF and validate result.document. schemaVersion is docir.v1. pages[].blockIds is the order. A table cell lives in block.rows.
A container PDF also has metadata.engine, metadata.pdfPageCount, and metadata.pdfTextLayerFastPath. result.manifest.decision.route is container. wait=true returns HTTP 200. Without the flag the response is HTTP 202 and the JSON is on the job links.
- jq the schemaVersion and the first page's blockIds.
- A measured PDF box uses unit pt. A block with no box omits bbox.
- The container document parserVersion is cloudflare-docparse-container.0.2.0.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"
curl -fsS -X POST \
"$DOCPARSE_URL/v1/parse?wait=true" \
-H "Authorization: Bearer $DOCPARSE_API_KEY" \
-F "file=@document.pdf" \
-F "mode=both" \
-o result.json
jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json
Frequently asked questions
Questions this guide answers
Does DocParse return JSON for a PDF?
Yes. A successful parse returns Markdown and docir.v1 JSON. The JSON has pages, blocks with ids and pageIndex, metadata.route, and metadata.warnings. The container parserVersion is cloudflare-docparse-container.0.2.0.
Is the JSON a replacement for Markdown?
Markdown is the readable projection. The JSON is the record applications use for pages, block order, tables, and citations. Both come from the same job.
Which endpoint returns the JSON?
POST /v1/parse returns both artifacts. wait=true completes inline with HTTP 200. Without that flag the job is accepted with HTTP 202 and the result is read from the job links.