Quick Start
Convert your first document with Docling for IBM watsonx in a few minutes
This guide takes you from a new account to your first converted document. It shows the same conversion two ways: with plain HTTP requests (curl) and with the Python SDK.
Both versions are also ready to run in the 01-quickstart folder of the examples repository: convert.sh (curl and jq, including the polling loop and the downloads) and convert.py (Python SDK, saves Markdown and DocLang).
1. Get your credentials
- Sign up at ibm.com/products/docling. You can start with a free trial.
- Open the Workbench, the web application for your Docling for IBM watsonx instance.
- Open API examples and copy two values:
- Service URL, your instance endpoint, for example
https://api.example.dcls.saas.ibm.com/your-instance-id - API key, which authenticates your requests
- Service URL, your instance endpoint, for example
Store both as environment variables. The Python SDK and the docling command line read these names automatically:
export DOCLING_SERVICE_URL="https://api.example.dcls.saas.ibm.com/your-instance-id"
export DOCLING_SERVICE_API_KEY="your-api-key"Keep your API key secret. Never commit it to version control. Use environment variables or a .env file that is excluded from git.
You can also try Docling without writing any code. On the Workbench Start page, the Play section lets you open the example documents (textual, tabular and scanned), upload your own, or enter a document URL and inspect the result. The rest of this guide uses the API.
2. Convert a document with the API
Conversions are asynchronous. You submit a document, poll until the task is done, and then fetch the result. See Concepts for details.
Submit a document by URL, and ask for Markdown and DocLang output:
curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/async" \
-H "X-Api-Key: ${DOCLING_SERVICE_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"sources": [{ "kind": "http", "url": "https://arxiv.org/pdf/2408.09869" }],
"options": { "to_formats": ["md", "doclang"] }
}'The response contains a task_id:
{ "task_id": "3f2c…", "task_type": "convert", "task_status": "pending", "task_position": 1 }Poll the status until task_status is success:
curl "${DOCLING_SERVICE_URL}/v1/status/poll/{TASK_ID}" \
-H "X-Api-Key: ${DOCLING_SERVICE_API_KEY}"Retrieve the result. It lists one download link per output format:
curl "${DOCLING_SERVICE_URL}/v1/result/{TASK_ID}" \
-H "X-Api-Key: ${DOCLING_SERVICE_API_KEY}"{
"documents": [
{
"filename": "2408.09869",
"status": "success",
"artifacts": [
{ "artifact_type": "markdown", "mime_type": "text/markdown", "uri": "https://…", "url_expires_at": "…" }
]
}
],
"num_converted": 1,
"num_succeeded": 1,
"num_failed": 0
}Download links expire, so save the files promptly. To upload a local file instead of a URL, use /v1/convert/file/async.
Full script, with the polling loop, file uploads and downloads: 01-quickstart/curl/convert.sh.
3. Convert a document with Python
Install the client:
pip install docling-clientThe SDK submits the document, polls for you and returns the converted document:
from docling.service_client import DoclingServiceClient
import os
with DoclingServiceClient(
url=os.environ["DOCLING_SERVICE_URL"],
api_key=os.environ["DOCLING_SERVICE_API_KEY"],
) as client:
result = client.convert(source="https://arxiv.org/pdf/2408.09869") # or a local Path
print(result.document.export_to_markdown())
result.document.save_as_doclang_archive("2408.09869.dclx") # DocLang, see step 4Full script, which accepts a URL or a local file and saves both outputs: 01-quickstart/python/convert.py.
docling-client is a lightweight package: it does not install any models, because all processing happens on the service. A Java SDK and a command-line tool are also available.
4. Look at the structure
Markdown is easy to read, but it flattens the document. The DocLang output keeps the full structure: headings, tables with their cells, figures, reading order and page positions. Drag the downloaded .dclx file onto the DocLang Viewer to explore it, or query it from the terminal with dclq as shown in Explore with DocLang.