Our cloud-hosted API documentation can be found here. With caveats and exceptions detailed below, the container image shares the same API.

Supported endpoints

The container currently supports:

/api/v1/convert (and the legacy alias /api/v1/marker) — document conversion to markdown, HTML, JSON, or chunks. Uses both the Marker and Chandra models.
/api/v1/ocr documented here.
/api/v1/extract — structured extraction via JSON schema. Supports fast and turbo extraction modes. Requires the Chandra model with the Lift model enabled; balanced and accurate extraction modes are not available on-prem.
/api/v1/usage documented here — provides usage analytics and performance metrics for your on-prem deployment.

Structured Extraction

/api/v1/extract requires page_schema and defaults to extraction_mode=fast. Fast mode parses the document and returns citations with the extracted data; extraction_mode=turbo reads page images and returns extracted JSON without parsed output, citations, or verification. Neither on-prem mode runs the cloud’s background confidence-scoring service. Enable models.lift.enabled=true in a Chandra Helm deployment before using extraction. Unsupported extraction mode values are rejected with HTTP 400. A missing model service is reported as a job error while polling.

Chandra-specific parameters

The following parameters are available on /api/v1/convert when running a Chandra-mode container (v1.5.0+):

Parameter	Type	Description
`exclude_block_types`	string	Comma-separated list of block type names to remove from the output (e.g., `Footnote,PageFooter`). Applied before rendering, so the filtered blocks are absent from all output formats (markdown, html, json, chunks). Invalid block type names return HTTP 400.

Example — strip page headers and footers from output:

curl -X POST http://localhost:8000/api/v1/convert \
  -F "file=@document.pdf" \
  -F "exclude_block_types=PageHeader,PageFooter"

exclude_block_types is available on Chandra-mode containers (v1.5.0+) only. Marker-mode containers do not support this parameter.

Crop Image Format

Set image_format=png to return extracted crops as PNG instead of the default JPEG. Accepted values are jpeg and png; the format also determines the image filename extensions referenced in the output. Both Marker and Chandra conversion support this setting. Invalid non-empty values return HTTP 400.

curl -X POST http://localhost:8000/api/v1/convert \
  -F "file=@document.pdf" \
  -F "output_format=html" \
  -F "image_format=png"

import requests

with open("document.pdf", "rb") as file:
    response = requests.post(
        "http://localhost:8000/api/v1/convert",
        files={"file": ("document.pdf", file, "application/pdf")},
        data={"output_format": "html", "image_format": "png"},
    )
response.raise_for_status()
print(response.json()["request_check_url"])

Poll request_check_url until completion to retrieve the converted output.

Optional Model Add-ons

Chandra deployments can enable these optional model services in their Helm values. Contact support@datalab.to for the model images and resource requirements.

Parameter on `/api/v1/convert`	Required Helm setting	Result
`word_bboxes=true`	`models.word-bbox.enabled=true`	Per-word bounding boxes and confidence scores in HTML spans
`additional_config={"link_captions":true}`	`models.caption-linker.enabled=true`	Links captions to their images or tables

If the required model service is disabled, the job fails. Check success and error while polling; accepting a request does not mean the add-on is available.

Scanned Redlines

On surya2 containers with a compatible redline checkpoint, pass redline=true to /api/v1/convert to preserve visible insertions, deletions, and comments as inline <ins>, <del>, and <comment> tags. Request HTML output to inspect these annotations.

MODEL_CLASS=surya2 alone is insufficient: the deployed checkpoint must support redlines. On other container modes, the worker reports success=false with an error during polling.

Partial Page Failures

Chandra conversion results include metadata.failed_pages, a list of original, 0-indexed page numbers that could not be parsed. Retry those pages using page_range. An empty list means no failed pages were reported; an absent field does not establish that all pages succeeded. metadata.page_stats can also include parse_status and parse_failure_reason. A page marked blank is not a failure. A degraded page has usable content but may need review.

Authentication

API authentication is not supported in the container. We assume customers will be running our image on their own infrastructure in private networks. You may send the X-API-Key header detailed here, but it will be ignored and any value works.

Supported File Types

Datalab’s API supports many file types. Chandra conversion supports PDFs and images, plus Office documents (including DOCX), HTML, and EPUB through local conversion to PDF. The required conversion tools must be included in your image. DOCX uses the local document renderer when available, with LibreOffice as a fallback. Conversion failures are reported in the job result.

Feature Parity

Feature	Cloud API	On-Premises
Document conversion (`/marker`)	Yes	Yes
OCR (`/ocr`)	Yes	Yes
Output formats (markdown, html, json, chunks)	Yes	Yes
Parse quality scoring	Yes	Yes
Chart understanding	Yes	Yes (Chandra containers only)
Page range selection	Yes	Yes
Block IDs	Yes	Yes
Token-efficient markdown	Yes	Yes
Form filling (`/fill`)	Yes	No
Create document (`/create-document`)	Yes	No
Thumbnails	Yes	No
Accurate mode	Yes	No
Fast mode	Yes	No
Link extraction	Yes	No
Checkpoints	Yes	No
File URL download	Yes	No
Structured extraction (`/extract`)	Yes	Yes — `fast` and `turbo` modes only (requires Lift model); `balanced` and `accurate` extraction modes not available
Document segmentation	Yes	No
`exclude_block_types` parameter	No	Yes — Chandra containers v1.5.0+ only
`image_format` parameter	No	Yes — JPEG or PNG crops in Marker and Chandra conversion
`word_bboxes` parameter	Yes	Yes — Chandra deployments with the `word-bbox` model enabled
Caption linking (`link_captions`)	Not a public Convert API option	Yes — Chandra deployments with the `caption-linker` model enabled
`redline` parameter	No	Yes — `surya2` with a compatible redline checkpoint

On-premises containers do not require API key authentication. Implement access control at the network or reverse proxy level.

Next Steps

Usage Analytics

Monitor request volumes, performance metrics, and system status.

Running the Container

Get the on-prem container up and running in minutes.

Cloud API Reference

Full REST API reference that the on-prem container mirrors.

On-Prem Overview

Compare open-source and paid on-prem options.

Welcome

On-prem

Platform

API

Supported endpoints

Structured Extraction

Chandra-specific parameters

Crop Image Format

Optional Model Add-ons

Scanned Redlines

Partial Page Failures

Authentication

Supported File Types

Feature Parity

Next Steps

Usage Analytics

Running the Container

Cloud API Reference

On-Prem Overview

​Supported endpoints

​Structured Extraction

​Chandra-specific parameters

​Crop Image Format

​Optional Model Add-ons

​Scanned Redlines

​Partial Page Failures

​Authentication

​Supported File Types

​Feature Parity

​Next Steps

Usage Analytics

Running the Container

Cloud API Reference

On-Prem Overview

Supported endpoints

Structured Extraction

Chandra-specific parameters

Crop Image Format

Optional Model Add-ons

Scanned Redlines

Partial Page Failures

Authentication

Supported File Types

Feature Parity

Next Steps