### Quick Start Java Client Example

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Demonstrates how to create a Docling Serve API client, build a conversion request for a document from a URL, and process the response. Ensure Jackson is included in your project.

```java
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.options.ConvertDocumentOptions;
import ai.docling.serve.api.convert.request.options.OutputFormat;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.request.target.InBodyTarget;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl("http://localhost:8000") // your Docling Serve URL
    .logRequests() // log HTTP requests
    .logResponses() // log HTTP responses
    .prettyPrint() // pretty-print JSON requests/responses
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
    .options(ConvertDocumentOptions.builder()
        .toFormat(OutputFormat.MARKDOWN)
        .includeImages(true)
        .build())
    .target(InBodyTarget.builder().build())
    .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) api.convertSource(request);
System.out.println(response.getDocument().getMarkdownContent());
```

--------------------------------

### Docling server startup logs

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/includes/docling-serve/serve-compatibility.md

Example output showing the server initialization and available documentation endpoints.

```text
Starting production server 🚀

Server started at http://0.0.0.0:5001
Documentation at http://0.0.0.0:5001/docs
Scalar docs at http://0.0.0.0:5001/scalar
```

--------------------------------

### HTTP Source Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Example of configuring an HTTP source for the Docling Serve API.

```APIDOC
## HTTP Source Configuration

### Description
Configure an HTTP source by providing a URL. Optional headers can also be set.

### Method
N/A (Client-side configuration)

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```java
import ai.docling.serve.api.convert.request.source.HttpSource;
import java.net.URI;

var httpSource = HttpSource.builder()
    .url(URI.create("https://example.com/file.pdf"))
    // .header("Authorization", "Bearer ...")
    .build();
```

### Response
N/A (Client-side configuration)
```

--------------------------------

### Docling Serve Startup Logs

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/includes/docling-serve/serve-compatibility.md

Initial server startup logs including plugin loading and instrumentation setup.

```text
Starting production server 🚀

Server started at http://0.0.0.0:5001
Documentation at http://0.0.0.0:5001/docs
Scalar docs at http://0.0.0.0:5001/scalar

Logs:
INFO:	04:23:47 - docling.models.factories.base_factory - Loading plugin 'docling_defaults'
INFO:	04:23:47 - docling.models.factories - Registered ocr engines: ['auto', 'easyocr', 'kserve_v2_ocr', 'ocrmac', 'rapidocr', 'tesserocr', 'tesseract']
INFO:	04:23:47 - docling_serve.otel_instrumentation - Setting up OpenTelemetry metrics
INFO:	04:23:47 - docling_serve.otel_instrumentation - Enabling Prometheus metrics export
```

--------------------------------

### Presigned URL Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Example of configuring the target to receive results as presigned download URLs.

```APIDOC
## Presigned URL Target Configuration

### Description
Configure the target to receive results as presigned download URLs. Requires docling-serve v1.22.0+.

### Method
N/A (Client-side configuration)

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```java
import ai.docling.serve.api.convert.request.target.PresignedUrlTarget;

var presigned = PresignedUrlTarget.builder().build();
```

### Response
N/A (Client-side configuration)
```

--------------------------------

### Initialize DoclingServeContainer

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Configures and starts a DoclingServeContainer for testing. Specify the Docker image, registry, and startup timeout. Ensure Testcontainers and Docker are set up correctly.

```java
var containerConfig = DoclingServeContainerConfig.builder()
        .image("{registry}/{image}:{tag}")
        .startupTimeout(Duration.ofMinutes(5))
        .build();
    var doclingContainer = new DoclingServeContainer(containerConfig);
    doclingContainer.start();
```

--------------------------------

### Convert Document Request

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testcontainers.md

Example of using the reference client to call the Convert endpoint for document conversion. This snippet demonstrates setting up the request with a source URL and desired output format.

```java
import java.net.URI;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
import ai.docling.serve.api.convert.request.options.OutputFormat;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.request.target.InBodyTarget;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

String baseUrl = docling.getApiUrl();
DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl(baseUrl)
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
    .options(ConvertDocumentOptions.builder()
        .toFormat(OutputFormat.MARKDOWN)
        .includeImages(true)
        .build())
    .target(InBodyTarget.builder().build())
    .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) api.convertSource(request);
// Assert on response.getDocument().getMarkdownContent(), errors, timings, etc.
```

--------------------------------

### File Upload (Base64) Source Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Example of configuring a file upload source using Base64 encoding.

```APIDOC
## File Upload (Base64) Source Configuration

### Description
Configure a file source by uploading file content as a Base64 encoded string, along with the filename.

### Method
N/A (Client-side configuration)

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```java
import ai.docling.serve.api.convert.request.source.FileSource;
import java.util.Base64;

byte[] bytes = /* read file */
var fileSource = FileSource.builder()
    .filename("report.pdf")
    .base64String(Base64.getEncoder().encodeToString(bytes))
    .build();
```

### Response
N/A (Client-side configuration)
```

--------------------------------

### Docling Server Production Logs

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/src/test/resources/markdownFileResults/expected-results.md

These logs show the server starting up, its network addresses, and incoming requests. They are useful for monitoring server activity and debugging.

```log
Starting production server 🚀

Server started at http://0.0.0.0:5001
Documentation at http://0.0.0.0:5001/docs
Scalar docs at http://0.0.0.0:5001/scalar

Logs:
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5001 (Press CTRL+C to quit)
INFO:     192.168.127.1:31567 - "GET /health HTTP/1.1" 200 OK
INFO:     192.168.127.1:62557 - "GET /health HTTP/1.1" 200 OK
INFO:     192.168.127.1:62557 - "POST /v1/convert/source HTTP/1.1" 200 OK
```

--------------------------------

### Example Results Markdown Output

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Excerpt from the generated `results.md` file, showing a table with tag, result status (success/failure), and links to details.

```markdown
# Results for ghcr.io/docling-project/docling-serve as of 2026-03-02T14:30:00.123456Z

| Tag | Result | Details |
| --- | ------ | ------- |
| v1.13.0 | ✅ SUCCESS | [Click for run details](#v1.13.0-details) |
| v1.12.0 | ❌ FAILURE | [Click for run details](#v1.12.0-details) |
```

--------------------------------

### In-Body Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Example of configuring the target to deliver results directly in the response body.

```APIDOC
## In-Body Target Configuration

### Description
Configure the target to receive results directly within the response body. This is the default behavior.

### Method
N/A (Client-side configuration)

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```java
import ai.docling.serve.api.convert.request.target.InBodyTarget;

var target = InBodyTarget.builder().build();
```

### Response
N/A (Client-side configuration)
```

--------------------------------

### HTTP PUT Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Example of configuring the target to upload results to a specified URI via HTTP PUT.

```APIDOC
## HTTP PUT Target Configuration

### Description
Configure the target to upload results to a specified URI using an HTTP PUT request. Optional headers can be included.

### Method
N/A (Client-side configuration)

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```java
import ai.docling.serve.api.convert.request.target.PutTarget;
import java.net.URI;

var put = PutTarget.builder()
    .uri(URI.create("https://storage.example.com/out/report.md"))
    // .header("Authorization", "Bearer ...")
    .build();
```

### Response
N/A (Client-side configuration)
```

--------------------------------

### Customizing the Report Template

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Example of using Qute syntax to iterate over test results and display tag information and status within the `results.md` template.

```markdown
{#each results.results}
  Tag: {it.tag}, Status: {it.result.status.name()}
{/each}
```

--------------------------------

### Test Specific Docling Serve Tags in Parallel

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testing.md

Run Docling version tests for a specified set of tags in parallel, controlling the number of concurrent tests. This example demonstrates overriding default parallelism and tag selection.

```bash
./gradlew :docling-version-tests:quarkusDev \
  -p 3 \
  -t v1.8.0 \
  -t v1.7.3 \
  -t v1.6.5
```

--------------------------------

### Full Project Build

Source: https://github.com/docling-project/docling-java/blob/main/CLAUDE.md

Execute a full build of the project using Gradle. This command ensures all modules are compiled and tested.

```bash
./gradlew --no-daemon build
```

--------------------------------

### Adding a New Registry Client Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Steps to integrate a new registry client by implementing an interface, annotating it, and configuring its URL in `application.yml`.

```yaml
quarkus:
  rest-client:
    my-registry:
      url: https://my-registry.io
```

--------------------------------

### Build and Run Docling Version Tests JAR

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testing.md

Build a runnable JAR for the Docling version tests and then execute it. This process involves building the application first and then running the generated JAR file. Ensure Docker is accessible.

```bash
# Build the application
./gradlew :docling-version-tests:build

# Run it
java -jar docling-testing/docling-version-tests/build/quarkus-app/quarkus-run.jar
```

--------------------------------

### Presigned URL Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure the target to receive results as presigned download URLs. Requires docling-serve v1.22.0 or later.

```java
import ai.docling.serve.api.convert.request.target.PresignedUrlTarget;
var presigned = PresignedUrlTarget.builder().build();
```

--------------------------------

### HTTP Source Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure an HTTP source to fetch documents from a given URL. Optional headers can be included.

```java
import ai.docling.serve.api.convert.request.source.HttpSource;

var httpSource = HttpSource.builder()
    .url(URI.create("https://example.com/file.pdf"))
    // .header("Authorization", "Bearer ...")
    .build();
```

--------------------------------

### Enable Request and Response Logging

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Enable lightweight logging for diagnostics by calling .logRequests() and .logResponses(). The .prettyPrint() option formats output for readability.

```java
DoclingServeApi noisy = DoclingServeApi.builder()
    .baseUrl("http://localhost:8000")
    .logRequests()
    .logResponses()
    .prettyPrint()
    .build();
```

--------------------------------

### Docling Server Production Logs

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/src/test/resources/markdownFileResults/expected-results.md

These logs show the startup sequence of the Docling production server, including network addresses for the server and documentation, as well as application-level logs detailing model loading and request processing.

```log
Starting production server 🚀

Server started at http://0.0.0.0:5001
Documentation at http://0.0.0.0:5001/docs
Scalar docs at http://0.0.0.0:5001/scalar

Logs:
INFO:     Started server process [1]
INFO:     Waiting for application startup.
onnxruntime cpuid_info warning: Unknown CPU vendor. cpuinfo_vendor value: 0
2025-11-05 12:45:13.644416238 [W:onnxruntime:Default, device_discovery.cc:164 DiscoverDevicesForPlatform] GPU device discovery failed: device_discovery.cc:89 ReadFileContents Failed to open file: "/sys/class/drm/card0/device/vendor"
[INFO] 2025-11-05 12:45:13,737 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2025-11-05 12:45:13,738 [RapidOCR] main.py:53: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/det/ch_PP-OCRv4_det_infer.onnx
[INFO] 2025-11-05 12:45:13,760 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2025-11-05 12:45:13,760 [RapidOCR] main.py:53: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/cls/ch_ppocr_mobile_v2.0_cls_infer.onnx
[INFO] 2025-11-05 12:45:13,771 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2025-11-05 12:45:13,771 [RapidOCR] main.py:53: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/rec/ch_PP-OCRv4_rec_infer.onnx
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:5001 (Press CTRL+C to quit)
INFO:     192.168.127.1:60019 - "GET /health HTTP/1.1" 200 OK
INFO:     192.168.127.1:18978 - "GET /health HTTP/1.1" 200 OK
INFO:     192.168.127.1:18978 - "POST /v1/convert/source HTTP/1.1" 200 OK
```

--------------------------------

### Run Version Tests in Development Mode

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Execute the CLI with specific arguments for testing. Use `-t` for specific tags and `-p` for parallelism.

```bash
./gradlew :docling-version-tests:quarkusDev -Dquarkus.args="-t v1.13.0 v1.12.0 -p 2"
```

```bash
./gradlew :docling-version-tests:quarkusDev -Dquarkus.args="-p 4 --exclude-tags-regex '.*rc.*'"
```

--------------------------------

### Convert Document with Presigned URL Target

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Demonstrates how to convert a document using an HTTP source and a PresignedUrlTarget. The response contains per-document artifact download links.

```java
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.request.target.PresignedUrlTarget;
import ai.docling.serve.api.convert.response.PreSignedUrlConvertResponse;

DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl("http://localhost:8000")
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
    .target(PresignedUrlTarget.builder().build())
    .build();

PreSignedUrlConvertResponse response = (PreSignedUrlConvertResponse) api.convertSource(request);
System.out.println("Converted: " + response.getNumSucceeded() + "/" + response.getNumConverted());

response.getDocuments().forEach(doc -> {
    System.out.println(doc.getFilename() + " -> " + doc.getStatus());
    doc.getArtifacts().forEach(artifact ->
        System.out.println("  " + artifact.getArtifactType() + ": " + artifact.getUri()));
});
```

--------------------------------

### Java Client: Convert Document Request

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Demonstrates building a document conversion request using the Docling Serve Java client. Specify the source URL, desired output format (e.g., Markdown), and whether to include images. The results are configured to be returned directly in the response body.

```java
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.options.ConvertDocumentOptions;
import ai.docling.serve.api.convert.request.options.OutputFormat;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.request.target.InBodyTarget;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl("http://localhost:8000") // your Docling Serve URL
    .logRequests() // log HTTP requests
    .logResponses() // log HTTP responses
    .prettyPrint() // pretty-print JSON requests/responses
    .apiKey("optionally your api key")
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869"))
        .build())
    .options(ConvertDocumentOptions.builder()
        .toFormat(OutputFormat.MARKDOWN) // request Markdown output
        .includeImages(true)
        .build())
    .target(InBodyTarget.builder().build()) // get results in the HTTP response body
    .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) api.convertSource(request);
System.out.println(response.getDocument().getMarkdownContent());
```

--------------------------------

### Customize HTTP Client for Docling Serve

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Supply and tune a java.net.http.HttpClient.Builder for Docling Serve requests, including connection timeouts, proxies, and SSL context.

```java
import java.net.http.HttpClient;
import java.time.Duration;

DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl("https://serve.example.com")
    .httpClientBuilder(HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(20))
        // .proxy(ProxySelector.of(new InetSocketAddress("proxy", 8080)))
        // .sslContext(customSslContext)
    )
    .build();
```

--------------------------------

### Configure DoclingServeContainer

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testcontainers.md

Use the fluent builder to customize container image, enable UI, set environment variables, and adjust startup timeout. An API key can also be set for consumer authentication.

```java
import java.time.Duration;
import java.util.Map;
import ai.docling.testcontainers.serve.config.DoclingServeContainerConfig;
import ai.docling.testcontainers.serve.DoclingServeContainer;

DoclingServeContainerConfig config = DoclingServeContainerConfig.builder()
    // Override the image if you need a different tag or registry
    .image("ghcr.io/docling-project/docling-serve:v1.9.0")
    // Enable the optional web UI served by Docling Serve
    .enableUi(true)
    // Pass environment variables to fine‑tune behavior
    .containerEnv(Map.of(
        // Example: configure OCR languages or pipeline hints if supported by the server
        "DOCLING_OCR_LANG", "eng,deu"
    ))
    // Increase startup timeout if your CI is slow to pull images
    .startupTimeout(Duration.ofMinutes(2))
    // Set an optional api key for that consumers must specify
    .apiKey("my-secret-api-key")
    .build();

DoclingServeContainer container = new DoclingServeContainer(config);
```

--------------------------------

### Create ConvertDocumentRequest

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Demonstrates how to build a `ConvertDocumentRequest` using its builder pattern. Specify the source, conversion options, and an optional delivery target.

```java
ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(/* one of the supported sources */)
    .options(/* conversion options */)
    .target(/* optional delivery target */)
    .build();
```

--------------------------------

### Check Docling version tag

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/includes/docling-serve/serve-compatibility.md

Displays the current compatible version tag for the project.

```markdown
Tag v1.20.0 is ok
```

--------------------------------

### File Upload Source (Base64)

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure a file source by uploading file content as a Base64 encoded string. Requires filename and the Base64 string.

```java
import java.util.Base64;
import ai.docling.serve.api.convert.request.source.FileSource;
byte[] bytes = /* read file */
var fileSource = FileSource.builder()
    .filename("report.pdf")
    .base64String(Base64.getEncoder().encodeToString(bytes))
    .build();
```

--------------------------------

### Docling Serve Version Status

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/includes/docling-serve/serve-compatibility.md

Confirmation message for the v1.22.0 release tag.

```markdown
Tag v1.22.0 is ok
```

--------------------------------

### Run Docling Version Tests with Gradle (Dev Mode)

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testing.md

Execute the Docling version tests in development mode using the Quarkus Gradle plugin for quick iterations. Ensure your user has access to the Docker daemon.

```bash
./gradlew :docling-version-tests:quarkusDev
```

--------------------------------

### Project Structure of Docling Version Tests

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Overview of the directory structure for the docling-version-tests module, highlighting main source files, test directories, and resources.

```text
docling-version-tests/
├── src/
│   ├── main/
│   │   ├── java/ai/docling/client/tester/
│   │   │   ├── VersionTestsCommand.java         # CLI entrypoint
│   │   │   ├── client/
│   │   │   │   ├── RegistryClient.java          # Registry API interface
│   │   │   │   ├── RegistryClientFactory.java   # Client factory
│   │   │   │   └── ghcr/
│   │   │   │       └── GHCRClient.java          # GHCR REST client
│   │   │   ├── config/
│   │   │   │   └── Config.java                  # Type-safe config
│   │   │   ├── domain/
│   │   │   │   ├── Tags.java                    # Tag domain model
│   │   │   │   ├── TagsTestRequest.java         # Test request
│   │   │   │   ├── TagsTestResults.java         # Test results
│   │   │   │   └── TagTestResult.java           # Single tag result
│   │   │   └── service/
│   │   │       ├── TagsTester.java              # Core testing logic
│   │   │       ├── WorkParallelizer.java        # Parallel execution
│   │   │       └── results/
│   │   │           ├── ResultsHandler.java      # Handler interface
│   │   │           ├── ResultsHandlers.java     # Handler aggregator
│   │   │           ├── MarkdownFileResultsHandler.java
│   │   │           └── GithubIssueResultsHandler.java
│   │   └── resources/
│   │       ├── application.yml                  # Quarkus config
│   │       └── templates/
│   │           └── results/
│   │               └── results.md               # Qute template
│   └── test/
│       ├── java/                                # Unit tests
│       └── resources/
│           └── wiremock/                        # WireMock stubs
└── build.gradle.kts
```

--------------------------------

### Handling Presigned URL Responses

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Demonstrates how to process the `PreSignedUrlConvertResponse` when using `PresignedUrlTarget`.

```APIDOC
## Handling Presigned URL Responses

### Description
When using `PresignedUrlTarget`, the API returns a `PreSignedUrlConvertResponse`. This response contains per-document results, including download links for artifacts, their types, and expiration times.

### Method
`api.convertSource(request)`

### Endpoint
N/A (Client-side invocation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **request** (ConvertDocumentRequest) - Required - The request object containing source and target configurations.

### Request Example
```java
import java.net.URI;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.request.target.PresignedUrlTarget;

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
    .target(PresignedUrlTarget.builder().build())
    .build();
```

### Response
#### Success Response (200)
- **PreSignedUrlConvertResponse** - Contains document results with artifact download links.

#### Response Example
```java
import ai.docling.serve.api.convert.response.PreSignedUrlConvertResponse;

// Assuming 'api' is an instance of the Docling Serve API client
PreSignedUrlConvertResponse response = (PreSignedUrlConvertResponse) api.convertSource(request);

response.getDocuments().forEach(doc -> {
    System.out.println(doc.getFilename() + " [" + doc.getStatus() + "]");
    doc.getArtifacts().forEach(artifact ->
        System.out.println("  " + artifact.getArtifactType() + ": " + artifact.getUri() 
            + (artifact.getUrlExpiresAt() != null ? " (expires: " + artifact.getUrlExpiresAt() + ")" : "")));
});
```
```

--------------------------------

### Set Docling Serve Base URL

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure the Docling Serve base URL using a String. The client enforces HTTP/1.1 for compatibility when using plain http://.

```java
DoclingServeApi api = DoclingServeApi.builder()
    .baseUrl("http://localhost:8000")
    .build();
```

--------------------------------

### CI/CD Integration for Version Tests

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Build and run the version tests application within a GitHub Actions workflow. This includes setting the GITHUB_TOKEN environment variable.

```yaml
- name: Run version tests
  run: |
    ./gradlew :docling-version-tests:build
    java -jar docling-testing/docling-version-tests/build/quarkus-app/quarkus-run.jar \
      --parallelism 2 \
      --output results \
      --create-github-issue
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Docling Serve Execution Logs

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/includes/docling-serve/serve-compatibility.md

Diagnostic logs showing document conversion processes, pipeline initialization, and API request handling.

```text
INFO:	04:24:51 - docling.utils.accelerator_utils - Accelerator device: 'cpu'
INFO:	04:24:51 - docling.datamodel.document - detected formats: [<InputFormat.HTML: 'html'>]
INFO:	04:24:51 - docling.document_converter - Going to convert document batch...
INFO:	04:24:51 - docling.document_converter - Initializing pipeline for SimplePipeline with options hash 7d306d2d021deac65a97d1a5f925362a
INFO:	04:24:51 - docling.pipeline.base_pipeline - Processing document file
INFO:	04:24:52 - docling.document_converter - Finished converting document file in 0.30 sec.
INFO:	04:24:52 - docling_jobkit.convert.results - Processed 1 docs in 0.31 seconds.
INFO:	04:24:52 - docling_jobkit.orchestrators.local.worker - Worker 1 completed job 1e79ab45-503d-40a4-b24e-edf70eb551e5 in 0.31 seconds
INFO:	04:24:52 - uvicorn.access - 172.17.0.1:33300 - "POST /v1/convert/source HTTP/1.1" 200
INFO:	04:24:52 - docling_serve.app - [TENANT_ID] Extracted tenant_id from header: 'default' (header_value: 'None')
INFO:	04:24:52 - docling_serve.app - [TENANT_ID] process_url endpoint received tenant_id='default'
INFO:	04:24:52 - docling_serve.app - [TENANT_ID] Preparing to enqueue with tenant_id='default' in metadata
INFO:	04:24:52 - docling_serve.app - [TENANT_ID] Task 2a63cf46-2ebf-4503-8a37-e9720986d48a created with tenant_id='default'
INFO:	04:24:52 - docling_jobkit.orchestrators.local.worker - Worker 0 processing task 2a63cf46-2ebf-4503-8a37-e9720986d48a
INFO:	04:24:52 - docling_jobkit.convert.manager - artifacts_path is set to a valid directory. No model weights will be downloaded at runtime.
INFO:	04:24:52 - docling.document_converter - Initializing pipeline for StandardPdfPipeline with options hash fb1751b09de6bdbe35ede48676ca8f82
INFO:	04:24:52 - docling.utils.accelerator_utils - Accelerator device: 'cpu'
[INFO] 2026-08-24 04:24:52,779 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2026-08-24 04:24:52,779 [RapidOCR] main.py:65: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/det/ch_PP-OCRv4_det_mobile.onnx
[INFO] 2026-08-24 04:24:52,879 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2026-08-24 04:24:52,879 [RapidOCR] main.py:65: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/cls/ch_ppocr_mobile_v2.0_cls_mobile.onnx
[INFO] 2026-08-24 04:24:52,925 [RapidOCR] base.py:22: Using engine_name: onnxruntime
[INFO] 2026-08-24 04:24:52,925 [RapidOCR] main.py:65: Using /opt/app-root/src/.cache/docling/models/RapidOcr/onnx/PP-OCRv4/rec/ch_PP-OCRv4_rec_mobile.onnx
INFO:	04:24:53 - docling.models.stages.ocr.auto_ocr_model - Auto OCR model selected rapidocr with onnxruntime.
INFO:	04:24:53 - docling.utils.accelerator_utils - Accelerator device: 'cpu'
Loading weights:   0%|          | 0/770 [00:00<?, ?it/s]Loading weights:  66%|██████▌   | 508/770 [00:00<00:00, 5078.01it/s]Loading weights: 100%|██████████| 770/770 [00:00<00:00, 5017.80it/s]
INFO:	04:24:53 - docling.utils.accelerator_utils - Accelerator device: 'cpu'
INFO:	04:24:53 - docling.datamodel.document - detected formats: [<InputFormat.HTML: 'html'>]
INFO:	04:24:53 - docling.document_converter - Going to convert document batch...
INFO:	04:24:53 - docling.document_converter - Initializing pipeline for SimplePipeline with options hash 7d306d2d021deac65a97d1a5f925362a
INFO:	04:24:53 - docling.pipeline.base_pipeline - Processing document file
INFO:	04:24:54 - docling.document_converter - Finished converting document file in 0.29 sec.
INFO:	04:24:54 - docling_jobkit.convert.results - Processed 1 docs in 0.36 seconds.
INFO:	04:24:54 - docling_jobkit.orchestrators.local.worker - Worker 0 completed job 2a63cf46-2ebf-4503-8a37-e9720986d48a in 0.36 seconds
INFO:	04:24:54 - uvicorn.access - 172.17.0.1:33300 - "POST /v1/convert/source HTTP/1.1" 200
INFO:	04:24:55 - uvicorn.access - 172.17.0.1:33300 - "GET /v1/clear/converters HTTP/1.1" 200
INFO:	04:24:55 - uvicorn.access - 172.17.0.1:33300 - "GET /v1/clear/results?older_then=3600 HTTP/1.1" 200
```

--------------------------------

### Configure Logging for API Client

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Duplicate an existing API client and enable logging for both requests and responses. This is useful for debugging.

```java
DoclingServeApi newApi = api.toBuilder()
    .logRequests()
    .logResponses()
    .build();
```

--------------------------------

### Apply Formatting Fixes with Spotless

Source: https://github.com/docling-project/docling-java/blob/main/CLAUDE.md

Automatically apply formatting fixes to the code using Spotless. This command ensures code adheres to defined style guidelines.

```bash
./gradlew --no-daemon spotlessApply
```

--------------------------------

### Add Gradle Dependency

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Include this dependency in your Gradle project to use the Docling Serve client.

```kotlin
dependencies {
  implementation("{{ gradle.project_groupId }}:{{ gradle.serve_client_artifactId }}:{{ gradle.project_version }}")
}
```

--------------------------------

### Add Docling Serve API Dependency (Gradle)

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Include the docling-serve-api dependency in your Gradle project for Java 17 compatibility.

```kotlin
dependencies {
  implementation("{{ gradle.project_groupId }}:{{ gradle.serve_api_artifactId }}:{{ gradle.project_version }}")
}
```

--------------------------------

### HTTP PUT Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure the target to upload conversion results to a specified URI using an HTTP PUT request. Optional headers can be included.

```java
import ai.docling.serve.api.convert.request.target.PutTarget;
var put = PutTarget.builder()
    .uri(URI.create("https://storage.example.com/out/report.md"))
    // .header("Authorization", "Bearer ...")
    .build();
```

--------------------------------

### Convert Document via HTTP Source

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/getting-started.md

Use this snippet to convert a document by providing its URL to the Docling Serve API. Ensure you have the DoclingServeApi configured with the correct base URL and optionally an API key.

```java
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;

DoclingServeApi doclingServeApi = DoclingServeApi.builder()
    .baseUrl("<location of docling serve instance>")
    .apiKey("optionally your api key")
    .build();

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(
        HttpSource.builder()
            .url(URI.create("https://arxiv.org/pdf/2408.09869"))
            .build()
    )
    .build();

InBodyConvertDocumentResponse response = (InBodyConvertDocumentResponse) doclingServeApi.convertSource(request);
System.out.println(response.getDocument().getMarkdownContent());
```

--------------------------------

### Configure Git User Information

Source: https://github.com/docling-project/docling-java/blob/main/CONTRIBUTING.md

Set your global Git user name and email. This information is used to attribute your contributions.

```bash
git config --global user.name "Your Full Name"
git config --global user.email your.email@example.com
```

--------------------------------

### Run Tests for Specific Subproject

Source: https://github.com/docling-project/docling-java/blob/main/CLAUDE.md

Execute tests for a particular subproject within the Gradle build. Replace ':docling-serve-client:test' with the relevant subproject path.

```bash
./gradlew --no-daemon :docling-serve-client:test
```

--------------------------------

### Add Docling Serve API Dependency (Maven)

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Add the docling-serve-api dependency to your Maven project to utilize the core Java API for Docling Serve.

```xml
<dependency>
  <groupId>{{ gradle.project_groupId }}</groupId>
  <artifactId>{{ gradle.serve_api_artifactId }}</artifactId>
  <version>{{ gradle.project_version }}</version>
</dependency>
```

--------------------------------

### Lint Check with Spotless

Source: https://github.com/docling-project/docling-java/blob/main/CLAUDE.md

Perform a lint check using Spotless to enforce import order and whitespace rules. This command checks code quality without applying fixes.

```bash
./gradlew --no-daemon spotlessCheck
```

--------------------------------

### Configure GitHub Issue Creation

Source: https://github.com/docling-project/docling-java/blob/main/docling-testing/docling-version-tests/README.md

Defines configuration properties for creating GitHub issues when tests fail. This requires setting the organization and repository name for the GitHub issue. Ensure the GITHUB_TOKEN environment variable is set for authentication.

```yaml
docling-version-tester:
  github:
    issue-creation:
      issue-org: docling-project  # default
      issue-repo: docling-java    # default
```

--------------------------------

### Add Maven Dependency

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Include this dependency in your Maven project to use the Docling Serve client.

```xml
<dependency>
  <groupId>{{ gradle.project_groupId }}</groupId>
  <artifactId>{{ gradle.serve_client_artifactId }}</artifactId>
  <version>{{ gradle.project_version }}</version>
</dependency>
```

--------------------------------

### Configure Client Logging

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

Allows for enabling request and response logging on the API client for diagnostic purposes.

```APIDOC
## Logging Configuration

### Description

Duplicate and tweak an existing `DoclingServeApi` implementation, optionally enabling request and response logging for diagnostics.

### Method

Builder pattern (assumed)

### Endpoint

N/A (Client-side configuration)

### Request Example
```java
DoclingServeApi newApi = api.toBuilder()
    .logRequests()
    .logResponses()
    .build();
```
```

--------------------------------

### Customize Output Directory and Disable GitHub Issues

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/testing.md

Execute Docling version tests with a custom output directory for artifacts and disable the automatic creation of GitHub issues upon failure. This is useful for managing test results and controlling notifications.

```bash
./gradlew :docling-version-tests:quarkusDev \
  -o ./my-results \
  --no-create-github-issue
```

--------------------------------

### Run Specific Test Class

Source: https://github.com/docling-project/docling-java/blob/main/CLAUDE.md

Execute a specific test class within a Gradle subproject. Ensure the test class name is correctly specified.

```bash
./gradlew --no-daemon :docling-serve-client:test --tests "ai.docling.serve.client.SomeTestClass"
```

--------------------------------

### In-Body Target Configuration

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Configure the target to receive conversion results directly in the response body. This is the default behavior.

```java
import ai.docling.serve.api.convert.request.target.InBodyTarget;
var target = InBodyTarget.builder().build();
```

--------------------------------

### Handling Presigned URL Responses

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-client.md

Process the `PreSignedUrlConvertResponse` when using `PresignedUrlTarget`. Iterates through documents and their artifacts, printing filenames, statuses, and artifact URIs with expiration times if available.

```java
import java.net.URI;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.request.target.PresignedUrlTarget;
import ai.docling.serve.api.convert.response.PreSignedUrlConvertResponse;

ConvertDocumentRequest request = ConvertDocumentRequest.builder()
    .source(HttpSource.builder().url(URI.create("https://arxiv.org/pdf/2408.09869")).build())
    .target(PresignedUrlTarget.builder().build())
    .build();

PreSignedUrlConvertResponse response = (PreSignedUrlConvertResponse) api.convertSource(request);

response.getDocuments().forEach(doc -> {
    System.out.println(doc.getFilename() + " [" + doc.getStatus() + "]");
    doc.getArtifacts().forEach(artifact ->
        System.out.println("  " + artifact.getArtifactType() + ": " + artifact.getUri() 
            + (artifact.getUrlExpiresAt() != null ? " (expires: " + artifact.getUrlExpiresAt() + ")" : "")));
});
```

--------------------------------

### Health Check

Source: https://github.com/docling-project/docling-java/blob/main/docs/src/doc/docs/docling-serve/serve-api.md

You can ping the service to check readiness and basic status.

```APIDOC
## Health Check

### Description

Ping the service to check readiness and basic status.

### Method

GET (assumed, based on typical health check patterns)

### Endpoint

/health (assumed, based on typical health check patterns)

### Response

#### Success Response (200)
- **status** (string) - The current status of the service.

### Request Example
```java
import ai.docling.serve.api.health.HealthCheckResponse;

HealthCheckResponse health = api.health();
System.out.println("Service status: " + health.getStatus());
```
```