Convert documents to Markdown, docling JSON, DocLang archives, LaTeX, HTML, Pandoc AST, or chunk records —
over docling.rs, on this server.
The API is described by /openapi.yaml (OpenAPI 3.1).
Try it
PDF/image inputs run the ML pipeline — the first conversion loads the models
(tens of seconds), repeats are fast. Markdown responses stream in as they convert.
Picking several files converts them as one batch (JSON results array).
API
| Method | Path | Description |
|---|---|---|
POST | /v1/convert |
Convert an upload (multipart/form-data, a file part — the filename's
extension selects the input format; several file parts convert as a batch and
answer a JSON results array) or a URL (application/json:
{"url": …, "file_name"?: …}). PDF/image responses carry an
X-Docling-Confidence summary header; to=json bodies embed the full
per-page confidence report. |
POST | /v1/convert/async |
The same request, answered immediately with {"task_id": …} — the job queues on
the server's concurrency bound and reuses the warm pipeline. |
GET | /v1/status/{id} |
Async job status: pending | started | success | failure. |
GET | /v1/result/{id} |
Async job result — the same response the sync endpoint would have sent; kept until the result TTL (default 10 min) evicts it. |
POST | /v1/convert/file, /v1/convert/source |
Python docling-serve's own API, for the clients written against it (Open WebUI, n8n,
Dify): files uploads or {"sources": […], "options": {…}} with
upstream's option names, answered as its ConvertDocumentResponse
(document.md_content, status, errors); /async
variants, /v1/status/poll/{id} and /v1alpha/… aliases too. |
GET | /v1/config | Server capabilities — currently {"allow_url_fetch": bool}, which this page adapts to. |
GET | /health | Liveness probe. |
GET | /ready | Readiness probe — 503 until --warmup finishes loading the ML models. |
GET | /openapi.yaml |
OpenAPI 3.1 description of this server — point Swagger UI, Redoc, or a client generator at it. |
Options
As query parameters, multipart text fields, or JSON keys (body wins over query):
| Option | Values | Description |
|---|---|---|
to | md (default) | json | html | text | dclx | chunks | latex | pandoc | vtt | images |
Markdown (streamed) · docling DoclingDocument JSON · HTML page · DocLang OPC archive (download) · LaTeX document · WebVTT subtitles from an audio/video transcript or a .vtt (#614) · Pandoc's AST as JSON (pipe it into pandoc -f json -t docx, odt, rst, typst, …; pictures per images) · chunker records (hierarchical + hybrid when a tokenizer is installed) · per-page PNG renders of a PDF (no conversion; combines with pages, capped at 100 pages per request by default). |
pandoc_api_version | 1.23 | to=pandoc: the Pandoc API your pandoc reads. Only 1.23 (Pandoc 3.x) is written; another version is a 400 instead of a document Pandoc would reject. |
strict | true/false | Cleaner strict Markdown dialect instead of byte-for-byte docling-legacy output. |
images | placeholder (default) | embedded | Markdown picture handling (embedded = base64 data URIs). |
no_ocr | true/false | PDF/image: keep layout + TableFormer, never OCR (docling's --no-ocr, do_ocr=False; #244, and since 2.0 the meaning of no_ocr, #611) — structure survives, pixel-only text comes back empty. A missing OCR model degrades to this instead of erroring. skip_ocr, its pre-2.0 name, is still read. |
text_layer_only | true/false | PDF/image: skip layout/OCR/TableFormer entirely; emit the embedded text layer only (what no_ocr meant before 2.0, #611). |
password | text | The password of an encrypted PDF or Office document — .docx/.xlsx/.pptx/.doc/.xls/.ppt (#611, #625; pdf_password, docling's name, is read too). |
no_table_former | true/false | PDF/image: geometric table reconstruction instead of the TableFormer model. |
no_text_panels | true/false | PDF/image: keep every detected picture as a picture — disable the demotion of uncaptioned dense-text "picture" regions into paragraphs. |
list_attachments | true/false | Email (.eml/.msg): append an Attachments section — names and content types only, never the payload. |
ebcdic_layout | JSON | EBCDIC (.ebc): the copybook layout as inline EbcdicLayout JSON — mandatory for the format. |
fetch_images | true/false | HTML/EPUB/MHTML/JATS: resolve external <img src> and embed the bytes. Outbound fetch — honored only when the server runs with --allow-url-fetch, otherwise ignored. |
asr_lang | auto (default) | a Whisper code (en, de, zh, …) | Audio/video: transcription language; auto detects it from the first 30 seconds. English-only presets always transcribe English. |
scale | 0.1–4.0 (default 2.0) | to=images: render scale in pixels per PDF point — 2.0 = 144 dpi, the ML pipeline's own render scale. |
force_full_page_ocr | true/false | PDF/image: OCR every page from its render, ignoring the embedded text layer (docling's force_full_page_ocr). |
heading_hierarchy | true/false | PDF/image: infer section-header levels (docling's HeadingHierarchyModel, #302) instead of flat ## headings. |
do_picture_classification | true/false | PDF/image: classify every picture with DocumentFigureClassifier (docling's do_picture_classification, #423) — the 26-class prediction lands on the JSON picture item's classification; Markdown unchanged. Needs .models/picture_classifier.onnx; a missing model warns and skips. |
do_code_enrichment | true/false | PDF/image: rewrite code blocks and detect their language with the CodeFormulaV2 VLM (docling's do_code_enrichment, #423). Needs .models/code_formula/; seconds per code region on CPU. |
do_formula_enrichment | true/false | PDF/image: decode display formulas to LaTeX with CodeFormulaV2 (docling's do_formula_enrichment, #423) — Markdown renders $$latex$$ instead of the placeholder comment. |
pages | A-B | N | PDF page window, 1-based inclusive (#80). |
ocr_lang | en (default) | ch | a BCP-47 tag (en-US, zh-Hans, iso:zh-CN) | OCR recognition language for scanned pages (ch = the multilingual docling-conformance model; BCP-47 tags for English/Chinese resolve to the same two models, #388). |
ocr_mode | default | full_page | layout_regions | pdf_aware_layout_regions | Which regions feed the OCR (docling's OcrMode, #254); full_page/layout_regions discard the text layer. |
ocr_scale | float | OCR render scale in px per PDF point (docling's OcrOptions.scale, default 3 = 216 dpi; unset reads the pipeline's own 2.0 render). |
compact_tables, skip_empty_cells | true/false | Unpadded | a | b | Markdown tables; drop empty cells from sparse XLSX/XLS grids (#271, docling.rs extensions). |
md_page_break_placeholder | string | Text inserted between pages in Markdown output (docling-serve's option; docling-core's MarkdownParams.page_break_placeholder), e.g. <!-- page break -->. Unset: no page breaks, docling's default. |
video_frames | int | Video: maximum sampled frames (0 = transcript only, #138). |
xbrl_taxonomy | string | XBRL: server-local relative directory holding the instance's taxonomy — extension schema and linkbases, taxonomy packages (docling's XBRLBackendOptions.taxonomy, #466); without it the fact graph has no presentation/calculation hierarchy. |
pipeline | standard (default) | vlm | PDF/image: the layout/TableFormer/OCR pipeline, or docling's VlmPipeline over a remote OpenAI-compatible vision-language endpoint (#304). |
vlm_endpoint, vlm_model, vlm_api_key, vlm_prompt, vlm_max_tokens | string / int | pipeline=vlm settings (defaults from DOCLING_RS_VLM_*); the endpoint is an outbound fetch, so it is honored only under --allow-url-fetch. |
chunker, chunk_tokenizer, chunk_max_tokens, chunk_merge_peers | hierarchical | hybrid / path / int / bool | to=chunks: pick one chunker (unset = both), a server-local tokenizer.json, the hybrid token budget and peer merging (#256). |
Examples
curl -F file=@paper.pdf localhost:5001/v1/convert # Markdown (streams)
curl -F file=@report.docx 'localhost:5001/v1/convert?to=json' # docling JSON
curl -F file=@sheet.xlsx 'localhost:5001/v1/convert?to=dclx' -OJ # DocLang archive
curl -F file=@page.html 'localhost:5001/v1/convert?to=chunks' # chunk records
curl -H 'content-type: application/json' \
-d '{"url": "https://example.com/doc.pdf", "to": "md"}' \
localhost:5001/v1/convert # convert a URL
curl -F file=@a.pdf -F file=@b.docx \
'localhost:5001/v1/convert?to=md' # batch → JSON results array
id=$(curl -F file=@big.pdf localhost:5001/v1/convert/async | jq -r .task_id)
curl localhost:5001/v1/status/$id # pending|started|success|failure
curl localhost:5001/v1/result/$id # the output, once done
curl -O localhost:5001/openapi.yaml # the API description