mirror of
https://github.com/docling-project/docling-serve.git
synced 2025-11-29 08:33:50 +00:00
81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# 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:
|
|
|
|
```jsonc
|
|
{
|
|
"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:
|
|
|
|
```jsonc
|
|
{
|
|
"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:
|
|
|
|
```jsonc
|
|
{
|
|
"options": {
|
|
"return_as_file": true // <-- to be removed
|
|
},
|
|
// ...
|
|
}
|
|
```
|
|
|
|
New version:
|
|
|
|
```jsonc
|
|
{
|
|
"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.
|
|
|
|
```sh
|
|
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._
|