API Reference

The Docling for IBM watsonx API provides a RESTful interface for converting documents into AI-ready formats.

Every HTTP request you make to the API endpoints require a Service URL and an API key. Access these by following the Quick Start guide.

The Service URL will look similar to:

https://api.example.dcls.saas.ibm.com/your-instance-id

Use this complete URL as your base URL for all API requests.

To use the API key, pass it in the X-Api-Key header of all API requests:

curl -H "X-Api-Key: your-api-key" \
  {SERVICE_URL}/v1/...

See the Basic Conversion examples for more guidance on how to use the Service URL and the API key.

API Workflow

Docling uses an asynchronous workflow for document conversion:

1. Submit - Upload or specify document source
2. Poll - Check conversion status
3. Retrieve - Get result artifacts, download URLs, and per-document statuses for the converted output

Endpoints

Conversion

• POST /v1/convert/file/async - Convert an uploaded file
• POST /v1/convert/source/async - Convert from a document URL
• POST /v1/convert/source/batch - Convert multiple documents, including from cloud storage

Status & Results

• GET /v1/status/poll/{task_id} - Check conversion status
• GET /v1/result/{task_id} - Retrieve conversion result artifacts

Rate Limits

Rate limits depend on your plan. If you exceed a limit, the API returns 429 Too Many Requests — back off and retry (see Polling Best Practices).

Contact your account manager for your plan's specific limits.

Error Handling

The API uses standard HTTP status codes. 2xx indicates success, 4xx a problem with the request, and 5xx a service-side error.

Error responses include an error code and a human-readable message, and may include a details object. For example, an authentication failure:

{
  "error": "token_exchange_failed",
  "message": "API key authentication failed",
  "details": {
    "instanceId": "...",
    "upstreamStatus": 400
  }
}

Calling an unknown endpoint returns the list of supported endpoints:

{
  "error": "Request failed",
  "message": "Endpoint /v1/convert/source is not supported. Supported: /v1/convert/file/async, /v1/convert/source/async, /health, /v1/result, /v1/status/poll"
}

When you receive a 429, retry with exponential backoff — see Polling Best Practices.

Supported Formats

Input Formats

• PDF documents
• Images (PNG, JPEG, TIFF)
• Microsoft Office (Word, Excel, PowerPoint)
• And more...

Output Formats

• Markdown - Human-readable text
• JSON - Structured data
• HTML - Web-ready format

Next Steps