Basic Conversion

This example walks through the process of converting either a local PDF or a PDF from the Internet to a markdown format. You can make requests to the API Endpoints, or use the Docling Python SDK or Java SDK (recommended).

For more customization options, refer to the Custom Conversion example or the API reference documentation.

API Endpoint Usage

The Docling for IBM watsonx API endpoint workflow for a file is as follows:

Submit a conversion request for a file, either locally or on the Internet.
Check on the status for the conversion request
Retrieve the finished result and save it

The Docling Python SDK or Docling Java SDK is recommended because it handles this process for the user.

Convert a Local File

Upload and convert a document from your local filesystem:

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/file/async" \
  -H "X-Api-Key: ${DOCLING_API_KEY}" \
  -F 'files=@"/path/to/doc.pdf"'

Ensure you use the -F flag and the correct filepath is listed.

You can upload up to 3 files in a single request by repeating the -F flag (when uploading more than one file, also include an options field — an empty object is allowed). To convert larger collections or ingest from cloud storage, use Batch Conversion.

Convert from URL

Convert a document directly from a URL:

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/async" \
  -H "X-Api-Key: ${DOCLING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {
        "kind": "http",
        "url": "https://arxiv.org/pdf/2311.18481"
      }
    ]
  }'

Ensure you use the -d flag and format the "sources" dictionary with the same fields as the example.

Checking Status

If the above request is successful, you will receive a TASK_ID in the response object. Use this TASK_ID to check on the status of your conversion request.

curl -X GET "${DOCLING_SERVICE_URL}/v1/status/poll/{TASK_ID}" \
  -H "X-Api-Key: ${DOCLING_API_KEY}"

Your conversion request may take longer than expected due to high traffic. Check the response object to see how far up the queue your request has moved.

Retrieve Results

Retrieve the conversion result once processing is complete. The response contains result artifacts with download URLs for the converted output:

curl -X GET "${DOCLING_SERVICE_URL}/v1/result/{TASK_ID}" \
  -H "X-Api-Key: ${DOCLING_API_KEY}"

Refer to the curl documentation for HTTP request features such as saving your result in a file.

Python SDK Usage

Convert from Local File

Upload and convert a document from your local filesystem:

from pathlib import Path
from docling.service_client import DoclingServiceClient
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:
    result = client.convert(
        source=Path("path/to/doc.pdf")
    )
    
    # Export to Markdown
    markdown = result.document.export_to_markdown()
    print(markdown)

Convert from URL

Convert a document directly from a URL:

from docling.service_client import DoclingServiceClient
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:
    result = client.convert(
        source="https://arxiv.org/pdf/2408.09869"
    )
    
    print(result.document.export_to_markdown())

Java SDK Usage

Add the client dependency with Gradle:

dependencies {
  implementation 'ai.docling:docling-serve-client:+'
}

The client also requires the docling-serve-api artifact and a Jackson 2 or 3 binding on your classpath — see the Java client documentation for the full dependency matrix.

Convert from Local File

import java.nio.file.Path;

import ai.docling.serve.api.DoclingServeApi;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

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();

        InBodyConvertDocumentResponse response =
            (InBodyConvertDocumentResponse) client.convertFiles(Path.of("path/to/doc.pdf"));
        System.out.println(response.getDocument().getMarkdownContent());
    }
}

Convert from URL

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.InBodyConvertDocumentResponse;

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/2311.18481"))
                .build())
            .build();

        InBodyConvertDocumentResponse response =
            (InBodyConvertDocumentResponse) client.convertSource(request);
        System.out.println(response.getDocument().getMarkdownContent());
    }
}

Basic Conversion

On this page