Blog / 25 posts

Parsing notes: the failure, then the record that avoids it

The blog is grouped by the question you arrived with: what parsing returns, which file you have, how retrieval should cite it, and how the job should run. Each post names a failure and the record that avoids it.

Start here / 4

Start here

What parsing returns, how it differs from OCR, and the failures that show up on real files.

03 / Blog · Aug 13, 2026

What a production document parsing API should actually do

A production document parsing API should normalize mixed files into readable text and structured document data, expose route and failure state, support synchronous and asynchronous use, and enforce access, cost, retention, and egress controls. Text extraction alone is only one stage of that contract.

Read post

By file type / 11

By file type

PDF, scans, slides, spreadsheets, Word, images, HTML, and CSV. Each note stays with that format.

01 / Blog · Aug 13, 2026

PDF to Markdown for LLMs: preserve structure before tokens

Converting PDF to Markdown for an LLM is useful only when reading order, headings, lists, tables, and page context survive the transformation. Keep a structured companion record beside Markdown so chunks and citations remain traceable to source pages and parser evidence.

Read post
05 / Blog · Sep 29, 2026

Read a multi-column PDF one column at a time

A multi-column PDF stores glyphs with positions, not paragraphs. Sorting every line from top to bottom mixes the columns. Detect the regions, read each column from top to bottom, then move to the next column.

Read post
06 / Blog · Sep 29, 2026

Keep the heading hierarchy when a PDF becomes Markdown

In a PDF, a heading is often just larger or bolder text at a position. Markdown needs that line marked as a heading, with a level that matches the outline. Later chunks should break on those headings instead of on an arbitrary token count.

Read post
07 / Blog · Sep 29, 2026

Turn a DOCX file into Markdown without flattening it

A Word file already stores paragraphs, styles, lists, and tables. Parsing it means carrying that structure into Markdown and into DocIR, including heading levels and list grouping. Flattening the document to a single string throws away the outline the author wrote.

Read post
08 / Blog · Sep 29, 2026

Parse a slide deck one slide at a time

A PowerPoint file is a sequence of slides, and each slide is a page. Parsing should keep the slide number, the title, and the body text in that order. Text boxes sorted only by coordinates scramble the slide the way columns scramble a PDF.

Read post
09 / Blog · Sep 29, 2026

Parse a workbook as sheets, headers, and rows

An Excel file is a set of sheets. Each sheet has a name, a header row, and records under those headers. Parsing should keep that shape. A single paragraph of cell values drops the header that makes a number mean something.

Read post
11 / Blog · Sep 29, 2026

Parse HTML and CSV without throwing away their structure

HTML already has headings, lists, and tables. CSV already has a header and rows. Parsing them means keeping that structure in Markdown and DocIR. Stripping an HTML page to a text blob, or joining a CSV into one paragraph, drops the only labels the file had.

Read post

RAG and retrieval / 5

RAG and retrieval

Chunk after the parse, keep page numbers on the citation, and index a knowledge base from the record.

01 / Blog · Aug 13, 2026

How to build a RAG document ingestion pipeline that can be debugged

A reliable RAG ingestion pipeline records each transformation from source to active index: identify and hash the file, parse it into a structured document, validate output, chunk by structure, embed versioned chunks, switch the active index, and evaluate retrieval with traceable citations.

Read post
02 / Blog · Sep 29, 2026

Chunk a PDF after you know its headings and pages

Chunk a PDF only after it has been parsed into headings, paragraphs, tables, and pages. Split on those boundaries. A fixed token window is the fallback when a section is too long, not the first cut. Every chunk should carry the page and the block ids it came from.

Read post
04 / Blog · Sep 29, 2026

Parse a knowledge-base file before you embed it

A knowledge base stays maintainable when each file has a content hash, a parse, and chunks that point at pages or sections. Embed those chunks. When the file changes, reparse that hash. When it does not, reuse the parse.

Read post

Jobs, routes, and retention / 5

Jobs, routes, and retention

When to leave the inline call, how deterministic and model routes differ, and what the job is allowed to store.

01 / Blog · Sep 29, 2026

Use a job when the file is too slow for one request

POST /v1/parse with wait=true returns the result inline for a short file. A scan, a large deck, or a burst of uploads belongs in a job with a visible state. A webhook, if you use one, is signed and delivered only to a host the workspace allows.

Read post
02 / Blog · Aug 13, 2026

Deterministic vs AI document parsing is a routing decision

Deterministic parsing is fast, repeatable, and effective when a document contains reliable native structure. OCR is necessary for pixels, and vision-language parsing can help with difficult layout or visual semantics. A production system should route by document evidence and policy instead of choosing one method for every file.

Read post
03 / Blog · Aug 13, 2026

How to evaluate a document parsing API without fooling yourself

Evaluate a document parsing API on representative document cohorts, label the source evidence you care about, score structure separately from text, record failures and latency, and measure the downstream task. Do not generalize from a single showcase PDF or an unsegmented average.

Read post
04 / Blog · Aug 13, 2026

DocIR: why document pipelines need a structured intermediate model

A structured intermediate model decouples downstream applications from parser-specific payloads. DocIR represents source metadata, pages, ordered typed blocks, optional geometry, assets, parser provenance, and warnings under a versioned schema while preserving Markdown as a readable projection.

Read post
05 / Blog · Aug 13, 2026

Document parsing security starts before the parser runs

A document parsing service accepts untrusted files and often reaches storage, queues, containers, models, URLs, and webhooks. Secure it with strict input bounds, isolated processing, server-owned routing, scoped credentials, outbound host policy, durable cost controls, minimal logs, tenant isolation, and explicit retention and purge.

Read post

Trial workspace

Send one text-based PDF.

Upload one text-based PDF under 20 MB. Call POST /v1/parse?wait=true with mode=both. Read result.markdown, result.document, and result.manifest. The trial covers 20 documents, 200 MB, and one active job.

Parse one text-based PDF 20 documents · 200 MB · deterministic trial · no payment card