01

The record, not the string

A useful parse keeps the file's identity, the pages, the order of blocks on each page, and the block type. Markdown is the readable view. A structured record such as DocIR keeps the page and block ids so a later chunk or citation can point back.

If the API returns only a string, the next system has to guess which page a sentence came from and whether a table cell stayed with its header.

02

OCR is one route

OCR reads characters from pixels. It is the right route for a scan or a photo. A digital PDF that already has a text layer can be read without OCR, and that result is repeatable.

DocParse starts on the deterministic path for text-based files. Image parsing, fast mode, high fidelity, and suspected scans require an approved paid workspace. The job stores the route, parser version, and warnings.

03

What to check on the first file

Parse one file your product already receives. Read the Markdown, then the page and block list. Check a table, a heading, and a sentence that sits in a second column.

The free workspace covers 20 text-based documents, 200 MB per month, one active job, and 20 MB per upload. That trial is deterministic.

04

Fields a caller can check

A successful parse returns Markdown and a docir.v1 document. The document has schemaVersion, parserVersion, pages, and blocks. Each block has an id, a type, and pageIndex. pages[].blockIds is the reading order. metadata.route and metadata.warnings say how the text was produced.

On the container path, parserVersion is cloudflare-docparse-container.0.2.0. A normal text-based PDF, DOCX, XLSX, HTML, or CSV records route container. A PPTX records route office-ooxml. pageIndex 0 is the first page in the file.

The block types in docir.v1 are heading, paragraph, list, table, formula, code, image, and unknown. The first block id is b000001, and later ids follow in order. POST /v1/parse is the public parse call. wait=true returns HTTP 200 when the inline parse finishes. Without that flag the call returns HTTP 202, and the client reads Markdown and DocIR from the job links.

  • Read Markdown for the words and DocIR for the structure.
  • Start at pages[].blockIds, not at the raw block array alone.
  • Treat metadata.warnings as part of the result.
  • The trial rejects image uploads and fastMode, highFidelity, and suspectedScanned with 403.
05

The file to send

Send one text-based PDF the product already receives. Read result.markdown, then result.document. Check a heading, a table, and a sentence that sits in a second column.

schemaVersion is docir.v1. The first block id is b000001. metadata.route is container. wait=true returns HTTP 200 with the three result fields. Without the flag the call returns HTTP 202.

  • pages[].blockIds is the order to trust.
  • metadata.warnings belongs with the result.
  • Image uploads and fastMode, highFidelity, and suspectedScanned return HTTP 403 on the trial.
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

What is document parsing?

Document parsing converts a PDF, Office file, HTML file, CSV, or image into Markdown plus a docir.v1 record of pages, ordered blocks, the route, and warnings. OCR and a flat text dump each cover a narrower part of that job.

Is document parsing the same as OCR?

OCR reads characters from pixels. Parsing also keeps pageIndex, reading order, headings, and tables when the file has them. DocParse writes the route that produced the text into metadata.route.

What does DocParse return?

POST /v1/parse returns Markdown and docir.v1 JSON. The container sets parserVersion to cloudflare-docparse-container.0.2.0. The job and metadata.route record the path, and metadata.warnings lists what the path skipped or fallback-read.