01

A complete string can still be the wrong document

Two columns sorted only by vertical position alternate left and right on every line. Every word is present. No paragraph is readable.

A table can keep every token and still attach a value to the neighboring header. Character counts will not catch it.

02

Empty success and the wrong route

A job can finish and still have missed a page. Read the warnings. A blank page and a page that used OCR are different outcomes.

If the file is a scan and the route was a text layer, the text you index may be furniture from a hidden layer or nothing useful. The route on the job is the first check.

03

What to inspect on one file

Pick a two-column page, a table, and a scanned page from the real upload mix. Compare the Markdown with the page, then check that DocIR still names the page and the block.

Do not send the string to a model until those three checks pass. The model will often smooth a broken order into a fluent answer.

04

Warnings the current parser actually writes

A digital PDF that qualifies for the text-layer path includes this metadata warning: Digital PDF text-layer fast path was used; request highFidelity for layout-VLM parsing. Rotated margin text, such as a sidebar or watermark, is dropped, and the warning says rotated margin text was excluded.

An empty page that local OCR cannot read warns that the page had no text and OCR produced no text. The page number in that warning is the file position, starting at 1. DocIR pageIndex for that same page is one less.

When the text-layer fast path skips OCR, an empty page uses a different warning: Page N had no extractable text; OCR was skipped by the PDF text-layer fast path. N is the 1-based file position. When local OCR does find text, the block warning is OCR fallback was used for an image-only PDF page, and that block's confidence is 0.5.

  • Compare Markdown order with the page before indexing.
  • Read metadata.warnings on the document, not only the HTTP status.
  • A block warning of OCR fallback means that page was image-only.
  • A full string with a warning is still a failed document for retrieval.
05

The file to send

Send one file that has already failed in your pipeline: a two-column page, a table, or a page with no text. Compare result.markdown with that page, then read metadata.warnings.

An empty page on the fast path says OCR was skipped. An empty page that ran OCR and found text says OCR fallback was used for an image-only PDF page. Save result.manifest.decision.route with the note.

  • A complete word count can still be the wrong column order.
  • Leave fastMode, highFidelity, and suspectedScanned off so the trial accepts the PDF.
  • Check one table cell that would be wrong if it moved one column.
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

Why does extracted PDF text read out of order?

PDF stores glyphs with positions. DocParse orders those boxes with a column-first XY-cut: it splits a full-height gutter before a full-width band, then reads the left region before the right. Sorting every line by vertical position alone interleaves the columns.

Should a warning block indexing?

Use the warning as a policy input. A missing page, excluded rotated margin text, or an OCR fallback on one page should not be indexed as a clean text-layer success.

Where does DocParse record the route?

The job records the route. docir.v1 repeats it in metadata.route, with parserVersion and metadata.warnings, beside the Markdown. A container PDF also records metadata.pdfTextLayerFastPath and metadata.pdfPageCount.