What a production document parsing API should actually do

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.