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 either make requests to the API Endpoints or use the Docling Python 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 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.

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 converted document once processing is complete:

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

To use the Docling Python SDK, please refer to the Docling for installation instructions and use case examples. You will need Python 3.9+ to install Docling.

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/2311.18481"
    )
    
    print(result.document.export_to_markdown())

Error Handling

It's good practice to introduce error handling in case there is an internal server error:

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:
    try:
        result = client.convert(source=Path("path/to/doc.pdf"))
        print(result.document.export_to_markdown())
    except Exception as e:
        print(f"Conversion failed: {e}")

Basic Conversion

On this page