docs: add API server usage pages (#3596)

mingxzhao · web-flow · commit ef9bb95e1e8e · 2026-06-14T07:32:19.000+02:00
* docs: add API server overview page (docling-serve)

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: add API server deployment page (launch modes + managed callout)

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: add API server REST API page

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: add API server sub-group to Usage nav

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: link the API server from the homepage features

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: add base64 upload example and subprocess warning to API server pages

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: address review — picture-description deprecation, ocr_preset, correct enrichment cross-links, admonition + terminology consistency

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: restructure API server overview &amp; deployment per team feedback

- Overview: 'When to use what?' table; 'Getting started' (service URL + optional
  API key, localhost for local runs) replacing the managed/self-hosted tabs
- Move the configuration model from Overview into Deployment
- Add a high-level 'Compute engines' (local / RQ / KFP-Ray) concept section

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: add Fully managed page for API server (Docling for IBM watsonx)

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: refine API server overview &amp; managed page per team feedback

- Overview: 'Run Docling directly...' wording + note REST API works from Python;
  reframe the MCP note as 'use the API server from an MCP agent' (remote mode);
  Getting started drops the local-launch how-to; trim the Architecture cross-link
- Managed page: retitle 'Why use the managed service'; add 'Available managed
  services' &gt; 'Docling for IBM watsonx' (product link; free trial kept hidden)
- nav label 'Fully managed' -&gt; 'Managed service'

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: document running the MCP server against a remote Docling API (remote mode)

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: document the DoclingServiceClient Python client on the REST API page

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

* docs: tighten DoclingServiceClient snippet per review

Use Path instead of a path string and drop the empty api_key argument.

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;

---------

Signed-off-by: Mingxuan Zhao &lt;43148277+mingxzhao@users.noreply.github.com&gt;
diff --git a/docs/index.md b/docs/index.md
@@ -46,6 +46,7 @@ Docling simplifies document processing, parsing diverse formats — including ad
 * 👓 Support of several Visual Language Models ([GraniteDocling](https://huggingface.co/ibm-granite/granite-docling-258M))
 * 🎙️ Audio support with Automatic Speech Recognition (ASR) models
 * 🔌 Connect to any agent using the [MCP server](https://docling-project.github.io/docling/usage/mcp/)
+* 🌐 Run Docling as a service with the [API server](https://docling-project.github.io/docling/usage/api_server/) (docling-serve)
 * 💻 Simple and convenient CLI
 
 ### What's new
diff --git a/docs/usage/api_server/deployment.md b/docs/usage/api_server/deployment.md
@@ -0,0 +1,141 @@
+<!-- Source: docling-serve@v1.21.0 — keep in sync on serve releases that touch config/deployment/usage. -->
+!!! info "Synced from docling-serve v1.21.0"
+    This page summarizes the [docling-serve](https://github.com/docling-project/docling-serve) documentation at **v1.21.0**. For the exhaustive reference, follow the links to the source repository.
+
+# Deployment
+
+Get docling-serve running on one machine fast. For cluster/production hardening, follow the links to the [docling-serve repo](https://github.com/docling-project/docling-serve/tree/v1.21.0/docs).
+
+Two independent choices shape how you run it:
+
+- **How you start the process** — the `docling-serve` command, or **Docker Compose**.
+- **Which [compute engine](#compute-engines) runs the jobs** (`DOCLING_SERVE_ENG_KIND`) — the in-process **Local** engine (default), or the Redis-backed **RQ** engine.
+
+| | Local engine (default) | RQ engine (Redis + workers) |
+|---|---|---|
+| **`docling-serve` command** | Quickstart / dev | Distributed |
+| **Docker Compose** | Containerized single node (+GPU) | → [serve repo](https://github.com/docling-project/docling-serve/tree/v1.21.0/docs/deploy-examples) |
+
+## Configuration
+
+docling-serve is configured by **CLI flags or environment variables**. Precedence is **environment variable > config file > defaults**.
+
+!!! warning "Subprocess gotcha"
+    When uvicorn runs with `--reload` or `--workers > 1` it spawns subprocesses, and CLI flags (e.g. `--enable-ui`, `--artifacts-path`) are ignored. Use the `DOCLING_SERVE_*` environment variables in those deployments.
+
+### Most common settings
+
+| Setting (env var) | What it does | Default |
+|---|---|---|
+| `UVICORN_HOST` / `UVICORN_PORT` | bind address / port | `0.0.0.0` / `5001` |
+| `UVICORN_WORKERS` | uvicorn worker processes | `1` |
+| `DOCLING_SERVE_API_KEY` | require an `X-Api-Key` header | unset |
+| `DOCLING_SERVE_ENABLE_UI` | serve the Gradio demo UI at `/ui` | `false` |
+| `DOCLING_SERVE_ARTIFACTS_PATH` | local path to pre-downloaded models | unset (auto-download) |
+| `DOCLING_SERVE_MAX_NUM_PAGES` / `DOCLING_SERVE_MAX_FILE_SIZE` | per-request limits | unset |
+| `DOCLING_SERVE_ENG_KIND` | async engine: `local` or `rq` (also `kfp`/`ray` — see serve repo) | `local` |
+
+See the full reference in the source repo: [`configuration.md`](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/configuration.md) and [`.env.example`](https://github.com/docling-project/docling-serve/blob/v1.21.0/.env.example).
+
+### Docling settings (env vars)
+
+These tune Docling itself and are read by the server too:
+
+| Env var | What it does | Default |
+|---|---|---|
+| `DOCLING_DEVICE` | inference device: `cpu` / `cuda` / `mps` | auto |
+| `DOCLING_NUM_THREADS` | CPU threads | runtime default |
+| `DOCLING_PERF_PAGE_BATCH_SIZE` | pages per batch | runtime default |
+| `DOCLING_PERF_ELEMENTS_BATCH_SIZE` | elements per batch | runtime default |
+| `DOCLING_DEBUG_PROFILE_PIPELINE_TIMINGS` | log per-stage timings | `false` |
+
+For how to *choose* device/perf values see [GPU support](../gpu.md). For offline / air-gapped model setup see the [FAQ](../../faq/index.md) and [Advanced options](../advanced_options.md); set `DOCLING_SERVE_ARTIFACTS_PATH` to a pre-populated model directory.
+
+## Compute engines
+
+docling-serve runs each conversion as an asynchronous job dispatched to a **compute engine**, chosen with `DOCLING_SERVE_ENG_KIND`:
+
+- **Local** (`local`, the default) — jobs run in an in-process thread pool inside the server. No external services; everything stays on one host. Tunable with `DOCLING_SERVE_ENG_LOC_NUM_WORKERS` (default `2`) and `DOCLING_SERVE_ENG_LOC_SHARE_MODELS` (default `false`). Best for a single machine.
+- **RQ** (`rq`) — jobs are queued in **Redis** and executed by separate `docling-serve rq-worker` processes, so the API tier and the conversion workers scale independently. Best for horizontal scaling and higher throughput.
+- **KFP / Ray** — Kubeflow Pipelines and Ray engines for cluster orchestration; see the [serve repo](https://github.com/docling-project/docling-serve/tree/v1.21.0/docs).
+
+## Running it
+
+### Simple command (Local engine — the default quickstart)
+
+```sh
+pip install "docling-serve[ui]"
+docling-serve run --enable-ui      # production-style: reload off, binds 0.0.0.0, UI off by default
+# docling-serve dev                # dev: auto-reload, binds 127.0.0.1, UI on (localhost only)
+```
+
+API at `http://localhost:5001`, interactive docs at `/docs`, demo UI at `/ui`. Smoke test:
+
+```sh
+curl -X POST "http://localhost:5001/v1/convert/source/async" \
+  -H "Content-Type: application/json" \
+  -d '{"http_sources": [{"url": "https://arxiv.org/pdf/2501.17887"}]}'
+```
+
+!!! note
+    The demo UI (`--enable-ui` / `DOCLING_SERVE_ENABLE_UI`) is a Gradio app; files it produces are cleared from its cache after ~10 hours. It is a demonstrator, not durable storage.
+
+### Docker Compose (incl. local GPU)
+
+Same server, containerized. The shipped compose examples are all-in-one containers that don't set `ENG_KIND`, so they run the default Local engine.
+
+```sh
+# Pure CPU (no compose)
+podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve
+
+# NVIDIA GPU
+docker compose -f compose-nvidia.yaml up -d
+
+# AMD GPU
+docker compose -f compose-amd.yaml up -d
+```
+
+Compose manifests: [`compose-nvidia.yaml`](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/compose-nvidia.yaml), [`compose-amd.yaml`](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/compose-amd.yaml).
+
+**GPU prerequisites** (host side; for the Python `AcceleratorOptions` view see [GPU support](../gpu.md) and [RTX GPU](../../getting_started/rtx.md)):
+
+- NVIDIA — driver ≥ 550.54.14 + `nvidia-container-toolkit` + the nvidia container runtime.
+- AMD — AMDGPU/ROCm ≥ 6.3; the ROCm image is **not published**, build it with `make docling-serve-rocm-image`. Detailed GID wiring: [serve repo](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deployment.md).
+
+!!! note
+    The compose files pin older image tags (`-cu126:main`, `-rocm72:main`) than the README image table; treat the [README image table](https://github.com/docling-project/docling-serve/blob/v1.21.0/README.md) as the source of truth and adjust the `image:` line if needed. There is no shipped single-CPU compose file — use the `podman` one-liner for pure CPU.
+
+### RQ engine (distributed: Redis + separate workers)
+
+The API enqueues jobs to Redis; conversion runs in separate `docling-serve rq-worker` processes.
+
+```sh
+# 1) Redis
+docker run -p 6379:6379 redis:7-alpine
+
+# 2) API server (enqueues jobs)
+DOCLING_SERVE_ENG_KIND=rq \
+DOCLING_SERVE_ENG_RQ_REDIS_URL=redis://localhost:6379/0 \
+docling-serve run
+
+# 3) one or more workers (do the conversion)
+DOCLING_SERVE_ENG_KIND=rq \
+DOCLING_SERVE_ENG_RQ_REDIS_URL=redis://localhost:6379/0 \
+docling-serve rq-worker
+```
+
+!!! warning
+    The API alone *accepts* jobs but nothing runs them without at least one `rq-worker`. `DOCLING_SERVE_ENG_RQ_REDIS_URL` is required (no default) and must be identical across every API and worker process.
+
+## Cluster, production & advanced variants
+
+These live in the docling-serve repo (run-time manifests aren't vendored here):
+
+- [OpenShift — simple deployment](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/docling-serve-simple.yaml)
+- [Multi-worker RQ on Kubernetes](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/docling-serve-rq-workers.yaml) (Redis + worker pods + secret)
+- [Secure deployment with oauth-proxy / TLS / Route](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/docling-serve-oauth.yaml)
+- [ReplicaSets with sticky sessions](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/deploy-examples/docling-serve-replicas-w-sticky-sessions.yaml) (task state is node-local)
+- [Model-cache PVC/Job](https://github.com/docling-project/docling-serve/blob/v1.21.0/docs/models.md) (pre-baking weights)
+- KFP / Ray engines, OpenTelemetry, CUDA image-tagging policy → [serve repo](https://github.com/docling-project/docling-serve/tree/v1.21.0/docs)
+
+Prefer not to run any of this yourself? See the [managed service](managed.md).
diff --git a/docs/usage/api_server/index.md b/docs/usage/api_server/index.md
@@ -0,0 +1,35 @@
+<!-- Source: docling-serve@v1.21.0 — keep in sync on serve releases that touch config/deployment/usage. -->
+!!! info "Synced from docling-serve v1.21.0"
+    This page summarizes the [docling-serve](https://github.com/docling-project/docling-serve) documentation at **v1.21.0**. For the exhaustive reference, follow the links to the source repository.
+
+# API server
+
+Run Docling as an HTTP service with [docling-serve](https://github.com/docling-project/docling-serve) — a FastAPI server that exposes Docling's document conversion over a REST API.
+
+## When to use what?
+
+| You want to… | Use |
+|---|---|
+| Call Docling over HTTP from any language (including Python), or share one conversion service | the **API server** — [self-host](deployment.md) it, or use a [managed service](managed.md) |
+| Run Docling directly (in-process) in a Python application | the [Python library](../../getting_started/quickstart.md) |
+| Run large-scale or distributed batch conversions | [Jobkit](../jobkit.md) |
+| Expose Docling as tools to an AI agent | the [MCP server](../mcp.md) |
+
+!!! note "Using the API server from an MCP agent"
+    The [MCP server](../mcp.md) can convert through this REST API instead of running Docling locally — set `DOCLING_CONVERSION_MODE=remote` and point it at your service URL. See [MCP server](../mcp.md).
+
+## Getting started
+
+To use the API server you need a running endpoint — [run your own](deployment.md) or use a [managed service](managed.md) — plus its **service URL** and, if the server requires one (`DOCLING_SERVE_API_KEY`), an **API key**. A local server defaults to `http://localhost:5001` (interactive API docs at `/docs`):
+
+```sh
+curl -X POST "http://localhost:5001/v1/convert/source/async" \
+  -H "Content-Type: application/json" \
+  -d '{"http_sources": [{"url": "https://arxiv.org/pdf/2501.17887"}]}'
+```
+
+See [Deployment](deployment.md) to run and configure it, and [REST API](rest_api.md) for the full API.
+
+## How it works
+
+A request hits the docling-serve API, which runs the conversion through Docling and returns the result (synchronously, or as an async task you poll). Background jobs run on a pluggable [compute engine](deployment.md#compute-engines) — in-process by default, or a Redis-backed queue for scaling. For the full API see [REST API](rest_api.md).
diff --git a/docs/usage/api_server/managed.md b/docs/usage/api_server/managed.md
@@ -0,0 +1,16 @@
+# Why use the managed service
+
+Running the API server yourself means operating infrastructure. A managed service removes that:
+
+- **No infrastructure to run.** No servers, GPUs, scaling, upgrades, or operational monitoring — it is hosted and maintained for you.
+- **Simple integration.** It exposes the same [REST API](rest_api.md) as the self-hosted server, so wiring it into applications and AI agents is just an HTTP call — point your client at the managed endpoint and go. Client code stays portable: typically you only swap the base URL and supply your API key.
+- **Same Docling conversion.** The same document understanding and output formats as the open-source library and server.
+
+## Available managed services
+
+### Docling for IBM watsonx
+
+A fully managed, hosted instance of the Docling service, exposing the same [REST API](rest_api.md) described in these pages. You provide the service URL and an API key, then call it like any other endpoint.
+
+- [Product page](https://www.ibm.com/products/docling)
+<!-- - [Free trial](https://www.ibm.com/products/docling) — hidden for the moment -->
diff --git a/docs/usage/api_server/rest_api.md b/docs/usage/api_server/rest_api.md
@@ -0,0 +1,172 @@
+<!-- Source: docling-serve@v1.21.0 — keep in sync on serve releases that touch config/deployment/usage. -->
+!!! info "Synced from docling-serve v1.21.0"
+    This page summarizes the [docling-serve](https://github.com/docling-project/docling-serve) documentation at **v1.21.0**. For the exhaustive reference, follow the links to the source repository.
+
+# REST API
+
+The docling-serve HTTP API. Examples target a local server at `http://localhost:5001`; on **Docling for IBM watsonx** use your service base URL and key.
+
+## Endpoints
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/v1/convert/source` | POST | convert from URLs / base64 sources (sync) |
+| `/v1/convert/file` | POST | convert uploaded files, multipart (sync) |
+| `/v1/convert/source/async`, `/v1/convert/file/async` | POST | submit an async task |
+| `/v1/status/poll/{task_id}` | GET | poll task status |
+| `/v1/status/ws/{task_id}` | WebSocket | subscribe to status |
+| `/v1/result/{task_id}` | GET | fetch a finished result |
+
+The full, interactive schema is always available at **`/docs`** (OpenAPI / Swagger) on any running server.
+
+## Authentication
+
+If `DOCLING_SERVE_API_KEY` is set on the server, send it on every request:
+
+```sh
+-H "X-Api-Key: <YOUR_KEY>"
+```
+
+## Python client
+
+Docling ships a Python client for the API server, so you don't have to hand-roll HTTP calls. It takes the service URL and an optional API key, and returns the same `ConversionResult` as the local `DocumentConverter`:
+
+```python
+from docling.service_client import DoclingServiceClient
+from docling.datamodel.service.options import ConvertDocumentsOptions
+
+with DoclingServiceClient(url="http://localhost:5001") as client:
+    result = client.convert(
+        source="https://arxiv.org/pdf/2501.17887",
+        options=ConvertDocumentsOptions(to_formats=["md"]),
+    )
+
+print(result.document.export_to_markdown())
+```
+
+`source` accepts an HTTP/HTTPS URL string, a local `pathlib.Path`, or a `DocumentStream`; use `convert_all([...])` to stream multiple conversion results. The `options` are the same [conversion options](#conversion-options-common) shown below. See the [examples](../../examples/index.md) for more recipes.
+
+## Conversion options (common)
+
+Pass these in the JSON body under `options`. This is the common subset — the **authoritative, full schema is the live OpenAPI docs at `/docs`** on any running server.
+
+| Option | Meaning |
+|---|---|
+| `from_formats` / `to_formats` | input / output formats (see [Supported formats](../supported_formats.md)) |
+| `image_export_mode` | how images are emitted (`placeholder` / `embedded` / `referenced`) |
+| `do_ocr` / `force_ocr` | enable / force OCR |
+| `ocr_preset` / `ocr_lang` | OCR preset and languages (`ocr_engine` is deprecated — prefer `ocr_preset`) |
+| `table_mode` | table-structure mode (`fast` / `accurate`) |
+| `pdf_backend` | PDF parsing backend |
+| `pipeline` | processing pipeline (e.g. standard / VLM) |
+| enrichment flags | code, formula, picture classification/description, chart |
+
+For full-page VLM conversion models see [Vision models](../vision_models.md); for picture-description models see [Enrichment features](../enrichments.md#picture-description) and [Model catalog](../model_catalog.md).
+
+## Example: convert a URL (async)
+
+```sh
+curl -X POST "http://localhost:5001/v1/convert/source/async" \
+  -H "Content-Type: application/json" \
+  -d '{"http_sources": [{"url": "https://arxiv.org/pdf/2501.17887"}]}'
+```
+
+For a synchronous call use `/v1/convert/source` with the same body.
+
+## Example: upload a file (multipart)
+
+The `/v1/convert/file` endpoint accepts one or more files as `multipart/form-data`, with options as form fields:
+
+```sh
+curl -X POST "http://localhost:5001/v1/convert/file" \
+  -H "Content-Type: multipart/form-data" \
+  -F "files=@2206.01062v1.pdf;type=application/pdf" \
+  -F "from_formats=pdf" \
+  -F "to_formats=md" \
+  -F "do_ocr=true" \
+  -F "image_export_mode=embedded" \
+  -F "table_mode=fast"
+```
+
+## Base64 file upload
+
+To send a file inline instead of multipart, POST to `/v1/convert/source` with `file_sources`. For large files, write the request body to a temp file and pass it with `-d @file` to avoid the shell's "Argument list too long" error:
+
+```sh
+# 1. base64-encode the file
+B64_DATA=$(base64 -w 0 /path/to/document.pdf)
+
+# 2. build the request body
+cat > /tmp/request_body.json <<EOF
+{
+  "file_sources": [{ "base64_string": "${B64_DATA}", "filename": "document.pdf" }]
+}
+EOF
+
+# 3. POST the request
+curl -X POST "http://localhost:5001/v1/convert/source" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/request_body.json
+```
+
+## Response format
+
+A single-file conversion returns JSON:
+
+```jsonc
+{
+  "document": {
+    "md_content": "",
+    "json_content": {},
+    "html_content": "",
+    "text_content": "",
+    "doctags_content": ""
+  },
+  "status": "success",   // success | partial_success | skipped | failure
+  "processing_time": 0.0,
+  "timings": {},
+  "errors": []
+}
+```
+
+Only the `*_content` fields you requested via `to_formats` are populated. `processing_time` is in seconds; `timings` carries per-component detail when enabled. If you request the zip `target`, or the job produces multiple files, the response is a zip archive instead of JSON.
+
+## Asynchronous API
+
+Both convert endpoints have `/async` variants. Submitting returns a task descriptor:
+
+```jsonc
+{
+  "task_id": "<task_id>",
+  "task_status": "pending",   // pending | started | success | failure
+  "task_position": 1,
+  "task_meta": null
+}
+```
+
+**Poll** until done — `GET /v1/status/poll/{task_id}`:
+
+```python
+import time
+import httpx
+
+base_url = "http://localhost:5001/v1"
+task = response.json()  # from the /async submission
+
+while task["task_status"] not in ("success", "failure"):
+    task = httpx.get(f"{base_url}/status/poll/{task['task_id']}").json()
+    time.sleep(5)
+```
+
+**Subscribe** via WebSocket — `/v1/status/ws/{task_id}` — for push updates (messages are JSON with `message` = `connection | update | error` plus the task object).
+
+**Fetch** the result when finished — `GET /v1/result/{task_id}`.
+
+## Picture description
+
+When picture-description (image captioning) enrichment is on, select the model with `picture_description_preset` (a named preset) or, for full control, `picture_description_custom_config`. The model can run locally (in-process) or via a remote OpenAI-compatible API endpoint; the remote path requires launching the server with `DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true`.
+
+!!! note
+    The older `picture_description_local` / `picture_description_api` parameters are deprecated at docling-serve v1.21.0 — migrate to `picture_description_preset` / `picture_description_custom_config`.
+
+See [Enrichment features](../enrichments.md#picture-description) for picture-description options, and [Model catalog](../model_catalog.md) for available models.
diff --git a/docs/usage/mcp.md b/docs/usage/mcp.md
diff --git a/mkdocs.yml b/mkdocs.yml
