Parsing is an intermediate data product
The parser sits between user-controlled files and systems that assume clean data. Its output becomes the evidence used by search, extraction, review, and models. That makes schema stability, provenance, and failure semantics as important as raw text accuracy.
At minimum, retain source identity, pages, ordered blocks, block types, readable text, route, parser version, warnings, and terminal errors. If the API returns only a string, every downstream consumer must guess where it came from and what was lost.
Separate request latency from job lifecycle
An inline endpoint is excellent for evaluation and small files. It is a poor universal contract for scans, large presentations, or burst traffic. A mature API supports an asynchronous job with explicit queued, running, retrying, succeeded, failed, canceled, and purged states.
Idempotency prevents client retries from duplicating work. Webhooks should be signed and delivered only to allowed destinations. Polling should return clear retry guidance rather than a generic 404 while output is pending.
- Inline mode for the first integration and bounded files.
- Async mode for variable latency and production load.
- Immutable identifiers for job, source, and result versions.
- Terminal errors distinct from transport errors.
Treat cost and security as API behavior
Do not let an untrusted caller choose an internal model or arbitrary outbound URL. Accept processing intent, validate source metadata, and choose routes on the server. Reserve provider usage before inference, cap daily exposure, and fail closed when accounting is unavailable.
Hash API keys, give them scopes and names, support revocation, and separate tenant limits from a global administrative credential. Retention and purge should be explicit endpoints with audit evidence.
Evaluate with downstream tasks
A parser comparison should include representative cohorts and score text completeness, reading order, tables, page attribution, latency, cost, and failures. Then measure the downstream task: retrieval accuracy, field extraction validation, or reviewer correction time.
A parser that wins on one clean PDF may lose on the actual mix. Segment results by source type, route, and parser version so routing and remediation decisions are grounded in evidence.
The file to send
Send one text-based PDF with the request below. wait=true returns HTTP 200 when the inline parse finishes, and result.markdown is in that body. The same call without the flag returns HTTP 202. That body accepts the job. The Markdown is on the job links.
For this PDF, result.manifest.decision.route is container and result.manifest.parserVersion is cloudflare-docparse.0.2.0. The DocIR parserVersion on the container path is cloudflare-docparse-container.0.2.0. A second upload while the job is still active returns HTTP 429, Tenant concurrent job capacity is exhausted.
- Read result.markdown, result.document, and result.manifest before writing a production client.
- schemaVersion is docir.v1. The first block id is b000001.
- Create the key in the workspace. It is shown once. Keep it on the server, with parse and read scopes.
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 the difference between OCR and document parsing?
OCR recognizes text in images. Document parsing additionally recovers hierarchy, reading order, tables, pages, metadata, and a structured representation suitable for applications.
Should a parsing API be synchronous?
It should often offer both. Inline responses simplify evaluation, while jobs and webhooks handle variable latency and production reliability.
What is the most important parser metric?
There is no single universal metric. Measure structure and completeness by document cohort and validate the downstream business or retrieval task.