Parse Document (v3)
Async PDF parsing that returns markdown. Supports inline upload, public URL, presigned upload for large files, and archive-based batches — all under one endpoint with per-key isolation.
POST
Overview
The v3 endpoint parses a PDF (or archive of PDFs) and returns markdown text for each page. Compared to v1/v2 it is intentionally simpler: no layout / OCR-engine / segment-analysis knobs, no segment tree in the response. You submit a PDF, you get markdown back. The pipeline picks the best model per page internally. The endpoint is async: every submission returns ajob_id you poll until the job reaches a terminal state.
Endpoint base URL: https://prod.visionapi.unsiloed.ai/v3/parse
The v3 surface has four routes:
Authentication
Every request requires anX-API-Key header. Two kinds of key are accepted, and both are isolated — you can only see the jobs created with your own key.
Personal benchmark keys are issued on request. Email aman@unsiloed.ai (or open an issue at github.com/Unsiloed-AI/unsiloed-olmocr-benchmark) with a one-line note about what you’re evaluating. Typical turnaround is same-day.
Guarantees
POST /v3/parse — Submit a single PDF
POST /v3/parse accepts three body shapes (auto-detected from the Content-Type header). All three submit the same async job and return the same response.
Body shape 1 — Inline multipart upload
For small PDFs (up to ~3 MB raw). Single HTTP call.PDF binary, sent as
multipart/form-data. Capped at ~3 MB raw (≈ 4 MB after base64 encoding inside API Gateway). For larger files use body shape 2 or 3.Optional query parameter on the request URL. Restrict OCR to a subset of pages.
"1-5": pages 1 through 5"1,3,5": specific pages- omitted: all pages
Body shape 2 — JSON with caller-hosted URL
For PDFs up to 50 MB that you already host (S3 public-read, S3 presigned, GitHub release asset, your own web server, etc.). Single HTTP call.Publicly fetchable
https:// URL to the PDF (a presigned S3 URL works). We fetch it. s3:// references are not accepted. URLs pointing at private IPs, link-local, or AWS instance metadata are rejected by an SSRF guard.Body shape 3 — JSON with file_id from a presigned upload
For PDFs up to 50 MB that you do not want to host publicly. First call POST /v3/parse/upload (below) to get a presigned upload_url and file_id; PUT your PDF to the URL; then submit the parse using the file_id.
The
file_id returned by POST /v3/parse/upload after you finish the PUT. Acts as the job_id for subsequent polling.You must use the same API key that minted the
file_id via POST /v3/parse/upload. Cross-key submissions return 404 (hiding existence) — this is how per-key isolation is enforced.Response (any body shape)
Job identifier (32-character UUID hex). Pass to
GET /v3/parse/{job_id} to poll. When you used body shape 3, this equals the file_id you submitted.POST /v3/parse/upload — Presigned upload URL
Returns a presigned S3PUT URL so you can upload a PDF directly (bypassing the API Gateway request size cap). Use this for the 3-call flow of body shape 3 above. No request body required — just an empty POST with the auth header.
Response
Opaque identifier. After you PUT the PDF to
upload_url, pass this back as {"file_id": "..."} to POST /v3/parse to start parsing.Presigned S3
PUT URL. 1-hour expiry from issuance. Send the PDF body directly to this URL with HTTP method PUT and Content-Type: application/pdf. The transfer bypasses our API Gateway entirely.Full 3-call flow
POST /v3/parse/batch — Archive of PDFs
Process many PDFs in one job. You host an archive of PDFs; we fetch it and process every PDF inside.Public or presigned
https:// URL to a .tar, .tar.gz/.tgz, or .zip archive of PDFs. Archive format is auto-detected by content sniffing the first bytes, not by file extension. Non-PDF files inside the archive are skipped silently.POST /v3/parse:
documents[] instead of pages[] (one entry per PDF in the archive) — see “Polling” below.
GET /v3/parse/ — Poll status + retrieve result
Query parameters
When set to
"markdown" and status is "done", returns concatenated page markdown as Content-Type: text/markdown; charset=utf-8 instead of a JSON envelope. Useful for curl ... | tee out.md. Ignored while the job is queued/running/failed.Response — while running
Response — single-PDF done
Per-page markdown. Each entry has
page (1-indexed integer) and markdown (string). Page order is ascending.Response — batch done
One entry per PDF found in the archive. Each entry has
pdf (relative path inside the archive), page_count, and pages[] (same shape as single-PDF). If a particular PDF failed, the entry has an error field instead of pages.If the JSON would exceed API Gateway’s 10 MB response cap, the response is
{ "job_id", "status": "done", "result_url" } instead — fetch result_url (presigned S3 GET) to download the same JSON. The schema of the downloaded JSON is identical to the inline shape, so clients can use one code path for both.Response — failed
Polling example
Reproduce our olmOCR-Bench score
The whole benchmark (1,403 PDFs) runs as onePOST /v3/parse/batch job. You score the returned markdown yourself with the unmodified upstream scorer, so the number is fully under your control.
1
Install the scorer and download the benchmark
2
Archive the PDFs and host the archive
The archive needs Any public or presigned
<category>/<file>.pdf at its root.https:// URL works. The job fetches the archive when it starts, so keep the URL valid for a few hours.3
Submit and wait
4
Download the result
5
Write the markdown where the scorer expects it
The scorer reads one file per page at
<bench_data>/<candidate>/<category>/<pdf stem>_pg<page>_repeat1.md. A PDF without output gets an empty file, so it fails its tests instead of invalidating the whole run.6
Score
Error responses
Code examples
See also
- Open-source benchmark harness + client — reproduces our published olmOCR-Bench numbers across vendors and includes a thin client (
clients/bench_via_api.py) that calls this endpoint, collects the returned markdown, and scores it with the unmodified upstream scorer. - v1 Parse Document — segmented response with bounding boxes, OCR data, and per-segment processing knobs.
- v2 Parse Document (Presigned Upload) — segmented response variant with presigned upload for larger files and higher throughput.

