Converting Multiple Documents
Convert more than one document in a single request with Docling for IBM watsonx
To convert more than one document, use the batch endpoint (/v1/convert/source/batch). It accepts any number of documents in a single request and returns one result per document. For converting a single document, see Basic Conversion; to ingest large collections from cloud storage, see Batch Conversion.
The batch endpoint is asynchronous: you submit the request, poll for status, and then retrieve the results.
API Endpoint Usage
Submit several documents by listing them under sources. Each source is a web URL ("kind": "http"):
curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/batch" \
-H "X-Api-Key: ${DOCLING_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{
"kind": "http",
"url": "https://arxiv.org/pdf/2408.09869"
},
{
"kind": "http",
"url": "https://arxiv.org/pdf/2501.17887"
}
],
"target": {
"kind": "presigned_url"
},
"options": {
"to_formats": ["md"]
}
}'The response is a task object with a task_id. Poll /v1/status/poll/{task_id} until the status is success, then retrieve the result from /v1/result/{task_id}.
When all your documents come from web URLs, you can ask for temporary download links by using the presigned_url target. The result then contains one entry per document, each with a download URL for every output format you requested:
{
"documents": [
{
"filename": "2408.09869",
"source_index": 0,
"source_uri": "https://arxiv.org/pdf/2408.09869",
"status": "success",
"artifacts": [
{
"artifact_type": "markdown",
"mime_type": "text/markdown",
"uri": "https://...",
"url_expires_at": "2026-06-15T12:00:00Z"
}
]
}
],
"num_converted": 2,
"num_succeeded": 2,
"num_partially_succeeded": 0,
"num_failed": 0,
"processing_time": 4.13
}Download artifacts promptly. Download URLs expire at url_expires_at. See Get Results for the full result shape.
In this example, each document is converted to Markdown. See the Custom Conversion examples for alternative output formats.
Python SDK Usage
Use submit_batch() to submit all documents at once. It returns a job you can wait on for the combined result:
from docling.service_client import DoclingServiceClient
from docling.datamodel.service.requests import AnyHttpSourceRequest
from docling.datamodel.service.targets import PresignedUrlTarget
import os
SERVICE_URL = os.getenv("DOCLING_SERVICE_URL")
API_KEY = os.getenv("DOCLING_API_KEY")
with DoclingServiceClient(url=SERVICE_URL, api_key=API_KEY) as client:
job = client.submit_batch(
sources=[
AnyHttpSourceRequest(url="https://arxiv.org/pdf/2408.09869"),
AnyHttpSourceRequest(url="https://arxiv.org/pdf/2501.17887"),
],
target=PresignedUrlTarget(),
output_formats=["md"],
)
response = job.result()
print(f"{response.num_succeeded}/{response.num_converted} converted")
for doc in response.documents:
print(doc.filename, doc.status)
for artifact in doc.artifacts:
print(" ", artifact.artifact_type, "->", artifact.uri)Java SDK Usage
Add multiple sources to a single request. Multiple documents are returned together as a ZIP archive:
import java.net.URI;
import ai.docling.serve.api.DoclingServeApi;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.response.ConvertDocumentResponse;
import ai.docling.serve.api.convert.response.ZipArchiveConvertDocumentResponse;
public class Main {
public static void main(String[] args) {
String serviceUrl = System.getenv("DOCLING_SERVICE_URL");
String apiKey = System.getenv("DOCLING_API_KEY");
DoclingServeApi client = DoclingServeApi.builder()
.baseUrl(serviceUrl)
.apiKey(apiKey)
.build();
ConvertDocumentRequest request = ConvertDocumentRequest.builder()
.source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
.source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2501.17887")).build())
.build();
ConvertDocumentResponse response = client.convertSource(request);
if (response instanceof ZipArchiveConvertDocumentResponse zip) {
System.out.println("Archive: " + zip.getFileName());
// Use zip.getInputStream() to save and extract each converted document
}
}
}