v1_migration.md

Migration to the v1 API

Docling Serve from the initial prototype v1alpha API to the stable v1 API. This page provides simple instructions to upgrade your application to the new API.

API changes

The breaking changes introduced in the v1 release of Docling Serve are designed to provide a stable schema which allows the project to provide new capabilities as new type of input sources, targets and also the definition of callback for event-driven applications.

Endpoint names

All endpoints are renamed from /v1alpha/ to /v1/.

Sources

When using the /v1/convert/source endpoint, input documents have to be specified with the sources: [] argument, which is replacing the usage of file_sources and http_sources.

Old version:

{
    "options": {},  // conversion options
    "file_sources": [  // input documents provided as base64-encoded strings
        {"base64_string": "abc123...", "filename": "file.pdf"}
    ],
    "http_sources": [  // input documents provided as http urls
        {"url": "https://..."}
    ]
}

New version:

{
    "options": {},  // conversion options
    "sources": [
        // input document provided as base64-encoded string
        {"kind": "file", "base64_string": "abc123...", "filename": "file.pdf"},
        // input document provided as http urls
        {"kind": "http", "url": "https://..."},
    ]
}

Targets

Switching between output formats, i.e. from the JSON inbody response to the zip archive response, users have to specify the target argument, which is replacing the usage of options.return_as_file.

Old version:

{
    "options": {
        "return_as_file": true  // <-- to be removed
    },
    // ...
}

New version:

{
    "options": {},
    "target": {"kind": "zip"},  // <-- add this
    // ...
}

Continue with the old API

If you are not able to apply the changes above to your application, please consider pinning of the previous v0.x container images, e.g.

podman run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve:v0.16.1

Note that the old prototype API will not be supported in new v1.x versions.