Docling Serve API Client#

Overview#

docling-serve-client is the reference Java HTTP client for connecting to a Docling Serve backend 1. It is part of the docling-java project, which provides a Java API for remote document processing. 2

The client-server architecture splits into two artifacts:

• docling-serve-api — framework-agnostic interfaces and request/response model types (DoclingServeApi, ConvertDocumentRequest, etc.) 3
• docling-serve-client — concrete HTTP implementation of DoclingServeApi using Java's built-in HttpClient and Jackson 4 5

Framework users: If you are on Quarkus, use the Quarkus Docling extension. For Spring Boot, use Arconia. The standalone docling-serve-client targets plain Java applications. 6

Architecture#

DoclingServeApi is an interface that composes five sub-APIs: DoclingServeHealthApi, DoclingServeConvertApi, DoclingServeChunkApi, DoclingServeClearApi, and DoclingServeTaskApi. The client implementation is resolved at runtime via Java SPI (ServiceLoader): if Jackson 3 is on the classpath, DoclingServeJackson3Client is used; otherwise DoclingServeJackson2Client is used. 7 8

Key Source Locations#

Backend API Endpoints#

The Docling Serve backend (Python/FastAPI) exposes the following endpoints relevant to the Java client 9:

When using plain http:// (e.g., local dev), the client enforces HTTP/1.1 to avoid HTTP/2 downgrade issues with FastAPI. 10

Request / Response Model#

ConvertDocumentRequest has three fields:

• sources — list of Source objects; each can be an HttpSource (URL) or FileSource (base64-encoded file) 11
• options — a ConvertDocumentOptions object controlling output format, OCR, images, etc. 12
• target — a Target specifying where results are delivered; null defaults to in-body response 13

Response types#

convertSource() returns a polymorphic ConvertDocumentResponse. Use getResponseType() to dispatch on the concrete type 14:

Source types#

• HttpSource — document at a URL, optionally with custom headers 15
• FileSource — base64-encoded bytes with a filename 16

Target types#

• InBodyTarget — result in response body (default) 17
• PresignedUrlTarget — presigned download URLs; requires Docling Serve ≥ v1.22.0 18
• PutTarget — upload result to arbitrary storage via HTTP PUT 19

Configuration#

The builder accepts:

• baseUrl(String | URI) — Docling Serve endpoint
• httpClientBuilder(HttpClient.Builder) — customize timeouts, proxy, TLS 20
• logRequests() / logResponses() / prettyPrint() — diagnostic logging 21
• apiKey(String) — optional API key authentication

Error Handling#

• Transport errors (DNS, TLS, timeout, connection reset) surface as standard Java exceptions from HttpClient. 22
• Structured conversion errors appear in the response body even when partial content is returned. On InBodyConvertDocumentResponse, inspect getErrors() for per-component error details. 23

Installation#

Add docling-serve-client (which transitively includes docling-serve-api) plus a Jackson 2 or 3 implementation. 24

// Gradle
dependencies {
  implementation("ai.docling:docling-serve-client:<version>")
}

<!-- Maven -->
<dependency>
  <groupId>ai.docling</groupId>
  <artifactId>docling-serve-client</artifactId>
  <version>VERSION</version>
</dependency>

See Maven Central for the current version. All published releases are tested weekly against all published Docling Serve versions. 25