> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.datalab.to/llms.txt
> Use this file to discover all available pages before exploring further.
# API
> Our on-prem container's API mimics Datalab's API.
Our cloud-hosted API documentation can be found [here](https://documentation.datalab.to/docs/welcome/api). 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](https://documentation.datalab.to/docs/welcome/api#ocr).
* `/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](/docs/on-prem/usage-analytics) — 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:
```bash theme={null}
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.
```bash cURL theme={null}
curl -X POST http://localhost:8000/api/v1/convert \
-F "file=@document.pdf" \
-F "output_format=html" \
-F "image_format=png"
```
```python Python (requests) theme={null}
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](mailto: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 ``, ``, and `` 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](https://documentation.datalab.to/docs/welcome/api#authentication), but it will be ignored and any value works.
# Supported File Types
Datalab's API supports [many file types](https://documentation.datalab.to/docs/common/supportedfiletypes).
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
Monitor request volumes, performance metrics, and system status.
Get the on-prem container up and running in minutes.
Full REST API reference that the on-prem container mirrors.
Compare open-source and paid on-prem options.