Docs

Each example parses a public URL and gets every page back in the response. Each page has its own status, so check for failed pages before using the markdown. To send a local file, see Request; over 50 pages, see Large documents.

The Python and TypeScript SDKs are typed clients for every endpoint, with retries and timeouts built in. They read your key from OPEN_DOC_ROUTER_API_KEY, or take it as api_key / apiKey.

Methods follow the endpoints: parse.create, parse.get, parse.delete, uploads.create, credits.get and models.list. In Python, a response's model_version is api_model_version, because Pydantic reserves the model_ prefix.

Set the model to an ID from the models page or from GET /v1/models, such as google/gemini-3.8-flash-low.

Each model runs a parsing recipe (its prompt and settings), and the recipe has a version that changes whenever its output can change.

POST /v1/parse with a JSON body and Authorization: Bearer <key>.

A document can be sent in three ways:

To upload, POST /v1/uploads returns a URL to PUT the file to within the hour. The file is deleted once a parse request reads it.

By default a request is sync (mode: "sync"), for up to 50 pages, and the response is a 200 with every page. A status of completed means every page worked, partial means some did, and failed means none did. Join pages[].markdown for a single markdown string.

{
  "id": "0f433d25-c2d5-40df-960f-1cb4c5ddc415",
  "status": "partial",
  "model": "google/gemini-3.8-flash-low",
  "model_version": "2026-09-28",
  "price_version": "2026-09-25",
  "pages": [
    { "page": 1, "status": "ok", "markdown": "# Attention Is All You Need ...", "cached": false,
      "usage": { "input_tokens": 757, "output_tokens": 811 }, "charge_usd": 0.00397 },
    { "page": 2, "status": "error",
      "error": { "code": "timeout", "message": "The page didn't finish before the request deadline" },
      "charge_usd": 0 }
  ],
  "usage": { "input_tokens": 757, "output_tokens": 811 },
  "charge_usd": 0.00397
}

GET /v1/parse/<id> shows what any request did and cost, page by page. Without cache: true it doesn't have a sync request's markdown, which is only in the POST response: if your connection drops, the request is still charged, and sending it again is a new request. With cache: true, add expand=markdown to read it again, and sending the same request again is free.

With layout: true, each successful page gets a layout: the page's size, and its elements in reading order. An element has a type (title, section_header, text, list_item, table, picture, chart, formula, caption, footnote, page_header, page_footer, code, form or key_value), the lines of the page's markdown it spans, and its boxes on the page.

{
  "page": 1, "status": "ok", "markdown": "# Attention Is All You Need\n\nThe dominant sequence ...",
  "layout": {
    "status": "ok", "width": 612, "height": 792,
    "elements": [
      { "type": "title", "lines": [0, 0], "confidence": 0.94,
        "boxes": [{ "x": 0.27, "y": 0.11, "w": 0.46, "h": 0.03 }] },
      { "type": "text", "lines": [2, 2], "confidence": 0.91,
        "boxes": [{ "x": 0.12, "y": 0.18, "w": 0.36, "h": 0.32 }, { "x": 0.52, "y": 0.18, "w": 0.36, "h": 0.12 }] },
      { "type": "picture", "lines": null, "confidence": 0.82,
        "boxes": [{ "x": 0.55, "y": 0.34, "w": 0.3, "h": 0.2 }] }
    ]
  }
}

• lines is the first and last line, counting from 0, after splitting the markdown on "\n" alone. Python's splitlines() also splits on other characters, so use split("\n"). It's null for a picture on the page that the markdown doesn't mention.
• A box's x, y, w and h are fractions of the page, from its top left. r, when present, is the clockwise angle of text printed at a slant. An element printed in pieces, such as a paragraph that continues in the next column, has a box per piece; one that couldn't be placed has none.
• If the layout of a page fails, the page keeps its markdown and its layout has a status of error with a code and message. The layout isn't charged.

Layout adds $0.20 per million tokens to each page whose layout comes back. For async requests, add expand=layout (or expand=markdown,layout) to the poll.

Over 50 pages, send "mode": "async" with "cache": true (up to 500 pages; a sync request over 50 is refused with too_large). Async requests store their results, so they need cache. The request returns a 202 with status: "processing" and an id. Poll GET /v1/parse/<id> until the status changes; pages_done shows progress. Then add expand=markdown to get the markdown. Every page usually comes back at once; results over 4 MB come in parts: while has_more is true, pass next_cursor as cursor.

The markdown is kept encrypted for 24 hours, until results_expire_at. DELETE /v1/parse/<id> deletes it sooner, and stops a running request; only pages that already ran are charged. Either way, the request's status and cost stay available.

Nothing from your document is kept unless you send cache: true:

• Without cache (sync only): the markdown is only in the POST response. The document is never stored.
• With cache: true (required for async): the results are kept encrypted for 24 hours after the request finishes, until results_expire_at. GET /v1/parse/<id>?expand=markdown reads them, and a later request for the same pages of the same document, with the same model and layout, is served from them for free. An async request's document is kept only until parsing ends.

DELETE /v1/parse/<id> deletes a request's stored results sooner, and they're no longer served from the cache. Each request's status, page count and cost stay in your history.

We retry each page once on timeouts, rate limits, provider errors and capacity, and when the model loops or doesn't transcribe. If a page still fails, send the document again with just those pages or try a different model. An uploaded file only works once, so upload the file again or use a URL.

{
  "model": "google/gemini-3.8-flash-low",
  "document": { "url": "https://arxiv.org/pdf/1706.03762" },
  "pages": "2,7"
}

A page error has a code, a message, and a reason when the provider gave one (such as SAFETY or max_tokens). From GET /v1/parse/<id>, message is the code's standard description unless you ask for expand=markdown.

A request that can't run returns { "error": { "code", "message" } } and is never charged. Every response has an X-Request-Id header, which also appears in your usage log.

Credit is prepaid: new accounts start with $5 of free credit, and you top up from $10 in the dashboard, plus a 5% fee on each top-up. Frontier models are charged at their providers' token prices, with no markup. Each successful page is charged for its tokens at the model's price, plus the layout price when you ask for layout. Failed, cached and blank pages are free.

To start, a request needs enough credit for its maximum charge: the model's most per page, times the number of pages. That amount is held while it runs, and whatever the pages didn't use is released when it finishes.