Concepts
How Docling for IBM watsonx processes documents, which outputs it produces, and how requests work
From a document to AI-ready data
When you submit a document, the service does much more than extract text. It runs a pipeline of specialized models:
The result is one structured document. It keeps what is usually lost when you only extract text:
- headings and their nesting
- tables with real rows, columns and merged cells
- figures and their captions
- lists and code blocks
- the natural reading order across columns
- the page and position of every element
Every output format is generated from this structured document.
Output formats
Pick the formats you need with to_formats. You can request several in one call.
| Format | to_formats value | Best for |
|---|---|---|
| Markdown | md | LLM prompts, quick reading, most RAG pipelines |
| HTML | html | Display in web applications |
| Plain text | text | Search indexing, simple NLP |
| DocLang | doclang | The full structure in an open, standard format |
| DocLang archive | dclx | DocLang plus the page and picture images, as a single file |
| JSON | json | Python applications that use the Docling SDK object model |
DocLang
DocLang is an open, XML-based format for structured documents, being standardized at ISO. Think of it as doing for documents what JSON does for data or HTML does for the web: any tool can read it.
Docling uses DocLang as its native structured output:
- Self-describing. Every element is typed (heading, paragraph, table cell, picture, caption, …) and carries its page and position.
- Addressable. A section, table or cell can be found with a path, for example
/heading[2]. That makes DocLang a good format for agents and for precise citations. - Portable. A
.dclxarchive bundles the document with its images in one file, ready to store, send or reopen later.
To inspect a DocLang file:
- Drop it onto the DocLang Viewer to see the structure next to the page.
- Query it from the terminal with
dclq.
See Explore with DocLang for both.
Chunks
For retrieval-augmented generation (RAG), documents have to be split into chunks that fit an embedding model. Docling chunks along the document's own structure: a chunk does not cut a table or a section in half, and each chunk carries its headings and page numbers. The service can deliver chunks directly into Kafka or a vector database. See Chunking.
Asynchronous tasks
Every conversion runs as a task:
- Submit. A
POSTto a convert endpoint returns atask_idimmediately. - Poll.
GET /v1/status/poll/{task_id}reportspending(with a queue position),processing,successorfailure. - Retrieve.
GET /v1/result/{task_id}returns the per-document status and the outputs.
The Python and Java SDKs and the command-line tool do the polling for you. Results are kept for 24 hours.
Single, batch or connectors?
| You want to… | Use | Results |
|---|---|---|
| Convert one document (URL or upload) | /v1/convert/source/async, /v1/convert/file/async | Download links |
| Convert several documents from URLs | /v1/convert/source/batch with presigned_url target | One download link per document and format |
| Ingest a whole bucket, folder or library | Batch endpoint with a source connector | Written to a storage target that you choose |
| Feed a RAG pipeline | Batch endpoint with chunking_options and a chunk target: Kafka, OpenSearch, AstraDB | Chunks streamed or indexed |
| Use documents from an AI assistant | MCP or agent skills | Converted on demand |