Convert multiple documents, including from cloud storage, using the Docling for IBM watsonx API

Convert Batch

Convert more than one document in a single request. Sources can be web URLs (HTTP/HTTPS) or cloud storage (S3), and results are delivered either as temporary download URLs or written to a cloud storage destination you specify.

Use this endpoint whenever you have more than one document. For a single document, use Convert Source or Convert File.

Endpoint

POST /v1/convert/source/batch

Request Headers

Header	Required	Description
`X-Api-Key`	Yes	Your API key for authentication
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`sources`	array	Yes	One or more source objects to convert (at least one)
`target`	object	Yes	Where converted results are delivered (see Targets)
`options`	object	No	Conversion options (see Options)
`callbacks`	array	No	Progress callback endpoints (see Progress Callbacks)

Sources

Each entry in sources is one of the following kinds. A single cloud storage source can represent many documents.

HTTP source

Parameter	Type	Required	Description
`kind`	string	Yes	Must be `"http"`
`url`	string	Yes	The URL of the document to convert
`headers`	object	No	Additional request headers used to fetch the URL (for example, authorization)

S3 source

Reads objects from an S3-compatible bucket. Every object under bucket/key_prefix is converted, up to max_num_elements.

Parameter	Type	Required	Description
`kind`	string	Yes	Must be `"s3"`
`endpoint`	string	Yes	S3 service endpoint, without protocol (for example, `s3.us-east-2.amazonaws.com`)
`access_key`	string	Yes	S3 access key
`secret_key`	string	Yes	S3 secret key
`bucket`	string	Yes	Bucket name to read from
`key_prefix`	string	No	Prefix for the object keys to read. Defaults to empty (the whole bucket)
`verify_ssl`	boolean	No	Use SSL to connect to S3. Defaults to `true`
`max_num_elements`	integer	No	Maximum number of objects to read from this source. Defaults to no limit

Targets

The target determines where converted results are delivered. The choice is constrained by your sources:

Sources	Allowed target	Result
All HTTP	`presigned_url` or `s3`	Temporary download URLs, or files written to your bucket
Any S3 source	`s3` (required)	Files written to your destination bucket

If any source reads from cloud storage, you must provide an s3 target. A web-only batch can use either target.

Presigned URL target

Parameter	Type	Required	Description
`kind`	string	Yes	Must be `"presigned_url"`

The result contains one entry per document, each with a download URL for every requested output format.

S3 target

Writes the converted outputs to an S3-compatible bucket you specify. This can be any bucket; it does not have to be a source bucket, and source objects are never modified.

Parameter	Type	Required	Description
`kind`	string	Yes	Must be `"s3"`
`endpoint`	string	Yes	S3 service endpoint, without protocol
`access_key`	string	Yes	S3 access key
`secret_key`	string	Yes	S3 secret key
`bucket`	string	Yes	Destination bucket for converted outputs
`key_prefix`	string	No	Prefix for the written object keys. Defaults to empty
`verify_ssl`	boolean	No	Use SSL to connect to S3. Defaults to `true`

Options

The options object supports the following parameters:

Parameter	Type	Default	Description
`to_formats`	array	`["md"]`	Output formats, any of: `"md"`, `"html"`, `"json"`, `"text"`, `"doclang"`

Response

Success Response (200 OK)

Returns a task object that can be used to poll for completion:

{
  "task_id": "{TASK_ID}",
  "task_type": "convert",
  "task_status": "pending",
  "task_position": 1,
  "task_meta": null,
  "failure": null,
  "error_message": null
}

See Convert Source for the task field descriptions.

Retrieving Results

Poll /v1/status/poll/{task_id} until the status is success, then call /v1/result/{task_id}. The result shape depends on the target:

presigned_url target — one entry per document with download URLs, plus result counters. See Get Results.
s3 target — converted files are written to your destination bucket; the result is a summary of counts:

{
  "num_converted": 312,
  "num_succeeded": 310,
  "num_partially_succeeded": 1,
  "num_failed": 1,
  "processing_time": 842.5
}

Field	Type	Description
`num_converted`	integer	Number of documents processed
`num_succeeded`	integer	Number converted successfully
`num_partially_succeeded`	integer	Number converted with partial success
`num_failed`	integer	Number that failed conversion
`processing_time`	number	Total processing time in seconds

Progress Callbacks

For long-running batches, you can have the service notify your own endpoint instead of polling. Each entry in callbacks describes a webhook:

Parameter	Type	Required	Description
`url`	string	Yes	URL the service POSTs progress updates to
`headers`	object	No	Additional headers to include on callback requests
`ca_cert`	string	No	Custom CA certificate (PEM) for verifying the callback endpoint

Each callback request has the shape:

{
  "task_id": "{TASK_ID}",
  "progress": {
    "kind": "update_processed",
    "num_processed": 120,
    "num_succeeded": 118,
    "num_partially_succeeded": 1,
    "num_failed": 1,
    "docs": [
      { "source": "incoming/report.pdf", "status": "success", "error": null }
    ]
  }
}

The progress object's kind is one of:

Kind	Description
`set_num_docs`	Sent once the total number of documents is known (`num_docs`)
`update_processed`	Running totals plus the documents processed in this update (`docs`)
`document_completed`	Sent after each document, with per-document detail (pages, tables, timing) and overall progress

Error Responses

See Error Handling for the full error model.

Status	Description
`400`	Bad request — malformed request
`401`	Unauthorized — missing or invalid API key
`422`	Validation error — invalid request shape, or an S3 source paired with a non-S3 target
`429`	Too many requests — rate limit exceeded
`500`	Internal server error
`502`	Gateway or upstream error

Examples

Find examples of using the batch endpoint in Converting Multiple Documents and Batch Conversion.

Convert Source - Convert a single document from a URL
Convert File - Upload and convert a single local file
Poll Status - Check conversion progress
Get Results - Retrieve conversion result artifacts

Convert Batch

On this page