Skip to main content

Broker API

The Document Service Broker exposes the main REST API for document operations.

The interactive Swagger UI is available at:

http://{broker-host}:8761/swagger-ui/index.html

The OpenAPI spec is available at http://{broker-host}:8761/v3/api-docs.

Base URL: http://{broker-host}:8761

Document operations​

Upload a document​

POST /documents

Upload a document as raw binary content. The request body is the raw file bytes.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringNoAssign a specific document ID
documentTitlequerystringNoDocument title
documentUrlquerystringNoDocument URL (alternative to binary body)
failOnUnsupportedquerybooleanNoIf true (default), throws an exception for unsupported formats
Content-TypeheaderstringYesMust be application/octet-stream

Response​

Returns the assigned document ID.

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

Errors​

StatusDescription
200Document uploaded successfully
400Bad request (invalid parameters or unsupported format)
409Conflict — a document with the same ID is already registered (binary upload only)

Example request​

curl -X POST http://localhost:8761/documents \
  -H "Content-Type: application/octet-stream" \
  --data-binary @my-document.pdf

Example response​

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

Upload a document layout​

POST /documents/layout

Registers a document in the broker from a pre-computed DocumentLayout object, without uploading the actual file. This is useful when the layout is already known and rendition can be bypassed entirely. The documentId field inside the body must be set.

Request body​

A DocumentLayout JSON object. The documentId field is required.

Parameters​

NameInTypeRequiredDescription
Content-TypeheaderstringYesMust be application/json

Response​

Empty body on success.

Errors​

StatusDescription
200Layout registered successfully
400Bad request — body is null or documentId is missing
409Conflict — a document with the same ID is already registered

Example request​

curl -X POST http://localhost:8761/documents/layout \
  -H "Content-Type: application/json" \
  -d '{"documentId": {"id": "my-doc-id"}, "pageCount": 2, "pages": [...]}'

Get document metadata​

GET /documents/{documentId}

Returns document metadata including MIME type, format, rendered format, and conversion order IDs.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns full document metadata.

{
  "documentId": {
    "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
  },
  "mimeType": "text/plain",
  "format": "txt",
  "renderedMimeType": "application/pdf",
  "renderedFormat": "pdf",
  "conversionOrderIds": {
    "pdf": {
      "id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"
    }
  },
  "documentTitle": null,
  "documentMetadata": "eyJtZXRhZGF0YU1hcCI6e319",
  "urlParameters": []
}

Errors​

StatusDescription
200Metadata returned successfully
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw

Example response​

{
  "documentId": {
    "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
  },
  "mimeType": "text/plain",
  "format": "txt",
  "renderedMimeType": "application/pdf",
  "renderedFormat": "pdf",
  "conversionOrderIds": {
    "pdf": {
      "id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"
    }
  },
  "documentTitle": null,
  "documentMetadata": "eyJtZXRhZGF0YU1hcCI6e319",
  "urlParameters": []
}

Get document file​

GET /documents/{documentId}/file

Returns the raw document content as a binary stream.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
formatquerystringNoRequested format. Plain format (e.g. pdf) waits for conversion and returns the converted file. Special values: rendered (equivalent to pdf) and compressed (returns a ZIP archive of the document). Omit to get the original file.

Response​

Binary content with the document's MIME type.

Errors​

StatusDescription
200Document file returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/file \
  --output document.pdf

Stream document file (chunked)​

GET /documents/{documentId}/file/chunk

Returns the document content in chunks for large files. Use the Range header to specify the byte range.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
formatquerystringNoDocument format
RangeheaderstringYesByte range, format: bytes=x-y

Response​

Binary content for the requested byte range.

Errors​

StatusDescription
206Partial content returned
404Document not found
416Range not satisfiable
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/file/chunk \
  -H "Range: bytes=0-1023"

Delete a document​

DELETE /documents/{documentId}

Evicts the document from the cache/storage.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200Document evicted, or document was not found (idempotent)

Example request​

curl -X DELETE http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw

Check document availability​

GET /documents/{documentId}/check

Checks whether the document is available and accessible.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns 200 OK with an empty body if the document exists.

Errors​

StatusDescription
200Document is available
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/check

Get document layout​

GET /documents/{documentId}/layout

Returns the document structure: page count, page dimensions, rotation, and DPI per page.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns page dimensions, rotation, and DPI for each page.

{
  "documentId": {
    "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
  },
  "mimeType": "text/plain",
  "pageDimensionsList": [
    {
      "width": 1191.0,
      "height": 842.0,
      "rotation": 0,
      "dpi": 72,
      "pageLayers": null
    }
  ]
}

Errors​

StatusDescription
200Layout returned successfully
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/layout

Example response​

{
  "documentId": {
    "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
  },
  "mimeType": "text/plain",
  "pageDimensionsList": [
    {
      "width": 1191.0,
      "height": 842.0,
      "rotation": 0,
      "dpi": 72,
      "pageLayers": null
    }
  ]
}

Get page image​

GET /documents/{documentId}/pages/{page}/image

Returns a rendered image (PNG) for the specified page.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
pagepathintegerYesPage number (0-based)
pageImageDescriptionquerystringNoImage descriptor specifying width, rotation, and optional filters

The pageImageDescription parameter uses the format IM_{width}_{rotation} with optional filters appended as _FILTERS~{type}~{value}.

Width and rotation:

IM_200_90

Requests an image of width 200 pixels with a 90-degree rotation.

With a single filter:

IM_200_90_FILTERS~C~35

Same image but with a contrast filter of 35.

With multiple filters:

IM_200_90_FILTERS~C~35~B~-100~I~50

Same image with contrast 35, brightness -100, and invert 50.

Available filter types:

FilterCodeDescription
ContrastCAdjust contrast
BrightnessBAdjust brightness
InvertIInvert colors

Response​

Binary PNG image (Content-Type: image/png).

Errors​

StatusDescription
200Image returned successfully
400Invalid page number or descriptor
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/documents/{documentId}/pages/0/image?pageImageDescription=IM_800_0" \
  --output page0.png

Get text positions​

GET /documents/{documentId}/pages/{page}/text/position

Returns extracted text with character-level positions for the specified page.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
pagepathintegerYesPage number (0-based)

Response​

Returns text elements with their bounding boxes, font information, and paragraph IDs.

{
  "pageNumber": 0,
  "positionTextList": [
    {
      "pageNumber": 0,
      "position": {
        "x": 36.0,
        "y": 41.6,
        "w": 288.6,
        "h": 12.0
      },
      "text": "Hello world",
      "individualWidths": [7.8, 7.8, 7.8],
      "fontSize": 13.0,
      "font": "Courier",
      "clickableDestination": null,
      "paragraphId": 0,
      "rightToLeftText": false,
      "rotation": 0
    }
  ],
  "imageHyperlinkPositionList": []
}

Errors​

StatusDescription
200Text positions returned
400Invalid page number
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/pages/0/text/position

Example response​

{
  "pageNumber": 0,
  "positionTextList": [
    {
      "pageNumber": 0,
      "position": {
        "x": 36.0,
        "y": 41.6,
        "w": 288.6,
        "h": 12.0
      },
      "text": "Hello world",
      "individualWidths": [7.8, 7.8, 7.8],
      "fontSize": 13.0,
      "font": "Courier",
      "clickableDestination": null,
      "paragraphId": 0,
      "rightToLeftText": false,
      "rotation": 0
    }
  ],
  "imageHyperlinkPositionList": []
}

Search text in a page​

GET /documents/{documentId}/pages/{page}/text

Searches for text positions in a specific page.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
pagepathintegerYesPage number (0-based)
searchTextquerystringYesText to search
caseSensitivequerybooleanNoCase-sensitive search (default: false)
accentSensitivequerybooleanNoAccent-sensitive search (default: false)
regexquerybooleanNoTreat searchText as a regular expression

Response​

Returns matching text positions with character ranges.

{
  "searchResults": [
    {
      "positionText": {
        "pageNumber": 0,
        "position": {"x": 36.0, "y": 41.6, "w": 55.0, "h": 12.0},
        "text": "Hello"
      },
      "textRangeList": [
        {"firstCharacter": 0, "lastCharacter": 5}
      ]
    }
  ]
}

Errors​

StatusDescription
200Search results returned
400Invalid page number or missing search text
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/pages/0/text?searchText=Hello"

Example response​

{
  "searchResults": [
    {
      "positionText": {
        "pageNumber": 0,
        "position": {"x": 36.0, "y": 41.6, "w": 55.0, "h": 12.0},
        "text": "Hello"
      },
      "textRangeList": [
        {"firstCharacter": 0, "lastCharacter": 5}
      ]
    }
  ]
}

Search text across the document​

GET /documents/{documentId}/search

Searches for text positions across multiple pages.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
fromPagequeryintegerYesStart page (0-based)
toPagequeryintegerNoEnd page (0-based). If absent, searches to the last page
searchTextquerystringYesText to search
caseSensitivequerybooleanNoCase-sensitive search
accentSensitivequerybooleanNoAccent-sensitive search
regexquerybooleanNoTreat searchText as a regular expression

Response​

Returns search results grouped by page, along with completion status.

{
  "documentId": {"id": "b64_..."},
  "searchText": "hello",
  "searchStatus": "COMPLETED",
  "lastPageSearched": 5,
  "pagesResults": {
    "0": [{"positionText": {"text": "hello", "position": {"x": 36.0, "y": 41.6, "w": 39.0, "h": 12.0}}}]
  }
}

Errors​

StatusDescription
200Search results returned
400Missing required parameters
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/search?fromPage=0&searchText=hello"

Example response​

{
  "documentId": {"id": "b64_..."},
  "searchText": "hello",
  "searchStatus": "COMPLETED",
  "lastPageSearched": 5,
  "pagesResults": {
    "0": [{"positionText": {"text": "hello", "position": {"x": 36.0, "y": 41.6, "w": 39.0, "h": 12.0}}}]
  }
}

Get pages containing text​

GET /documents/{documentId}/pages

Returns a list of page numbers that contain the search text.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID
searchTextquerystringYesText to search
caseSensitivequerybooleanNoCase-sensitive search
accentSensitivequerybooleanNoAccent-sensitive search
regexquerybooleanNoTreat searchText as a regular expression

Response​

Returns the document ID, the searched text, and a list of matching page numbers.

{
  "uuid": {"id": "b64_..."},
  "searchText": "hello",
  "pageList": [0, 2, 5]
}

Errors​

StatusDescription
200Page list returned
400Missing search text
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/pages?searchText=hello"

Example response​

{
  "uuid": {"id": "b64_..."},
  "searchText": "hello",
  "pageList": [0, 2, 5]
}

Get bookmarks​

GET /documents/{documentId}/bookmarks

Returns the document outline (table of contents).

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns a tree of bookmarks with page targets and child nodes.

{
  "bookmarks": [
    {
      "title": "Chapter 1",
      "page": 0,
      "textPosition": 0.0,
      "nodeOpen": true,
      "children": [],
      "namedDestination": null,
      "fileName": null,
      "shouldOpenInNewWindow": false
    }
  ]
}

Errors​

StatusDescription
200Bookmarks returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/bookmarks

Example response​

{
  "bookmarks": [
    {
      "title": "Chapter 1",
      "page": 0,
      "textPosition": 0.0,
      "nodeOpen": true,
      "children": [],
      "namedDestination": null,
      "fileName": null,
      "shouldOpenInNewWindow": false
    }
  ]
}

Get named destinations​

GET /documents/{documentId}/destinations

Returns named destinations (internal document links).

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns a list of named destinations with their target pages.

{
  "documentId": {"id": "b64_..."},
  "namedDestinations": [
    {"name": "section1", "page": 3}
  ]
}

Errors​

StatusDescription
200Destinations returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/destinations

Example response​

{
  "documentId": {"id": "b64_..."},
  "namedDestinations": [
    {"name": "section1", "page": 3}
  ]
}

Get digital signatures​

GET /documents/{documentId}/signatures

Returns digital signature information and validation status.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns signature details including signer, date, reason, and integrity status.

{
  "signatures": [
    {
      "name": "Signature1",
      "signer": "CN=John Doe",
      "date": "2026-01-15T10:30:00Z",
      "reason": "Approval",
      "location": "Paris",
      "wrongIntegrity": false,
      "unknownCertificate": false,
      "signatureException": false
    }
  ],
  "wronglySigned": false,
  "integrity": true
}

Errors​

StatusDescription
200Signatures returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/signatures

Example response​

{
  "signatures": [
    {
      "name": "Signature1",
      "signer": "CN=John Doe",
      "date": "2026-01-15T10:30:00Z",
      "reason": "Approval",
      "location": "Paris",
      "wrongIntegrity": false,
      "unknownCertificate": false,
      "signatureException": false
    }
  ],
  "wronglySigned": false,
  "integrity": true
}

Get printable document​

GET /documents/{documentId}/printable

Returns a print-ready version of the document as binary content.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Binary content suitable for printing.

Errors​

StatusDescription
200Printable document returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/printable \
  --output printable.pdf

Get document annotations file​

GET /documents/{documentId}/file/annotations

Returns the XFDF annotations file associated with the document.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

XFDF annotations file content.

Errors​

StatusDescription
200Annotations file returned
404Document not found or no annotations
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/file/annotations

Get document conversions​

GET /documents/{documentId}/conversions

Returns conversion order IDs associated with a specific document.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesThe document ID

Response​

Returns an array of conversion order IDs.

[
  {"id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"}
]

Errors​

StatusDescription
200Conversion IDs returned
404Document not found
500Internal server error

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/conversions

Example response​

[
  {"id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"}
]

Conversion operations​

Queue a conversion​

POST /conversions

Submits a document for asynchronous format conversion.

Parameters​

NameInTypeRequiredDescription
Content-TypeheaderstringYesMust be application/json

Request body:

{
  "documentId": {"id": "b64_..."},
  "format": "pdf"
}

Response​

Returns the conversion order ID for polling.

{
  "conversionOrderId": {"id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"}
}

Errors​

StatusDescription
200Conversion queued
400Bad request (invalid body or format)
404Document not found
500Internal server error

Example request​

curl -X POST http://localhost:8761/conversions \
  -H "Content-Type: application/json" \
  -d '{"documentId": {"id": "b64_..."}, "format": "pdf"}'

Example response​

{
  "conversionOrderId": {"id": "b26207dc-22b8-4cc4-a448-9b377ad5b706"}
}

Get all conversion orders​

GET /conversions

Returns all conversion orders currently tracked by the broker.

Parameters​

None.

Response​

Returns an array of conversion order objects with their current state.

[
  {
    "conversionOrderId": {"id": "b26207dc-..."},
    "documentId": {"id": "b64_..."},
    "currentState": "PROCESSED",
    "format": "pdf",
    "queuedDate": "2026-03-16T14:00:00Z",
    "processedDate": "2026-03-16T14:00:02Z",
    "processingTime": 2000,
    "errorMessage": null
  }
]

Errors​

StatusDescription
200Orders returned
500Internal server error

Example request​

curl http://localhost:8761/conversions

Example response​

[
  {
    "conversionOrderId": {"id": "b26207dc-..."},
    "documentId": {"id": "b64_..."},
    "currentState": "PROCESSED",
    "format": "pdf",
    "queuedDate": "2026-03-16T14:00:00Z",
    "processedDate": "2026-03-16T14:00:02Z",
    "processingTime": 2000,
    "errorMessage": null
  }
]

Poll conversion status​

GET /conversions/{conversionOrderId}

Returns the current status of a conversion order. Possible states: QUEUED, PROCESSING, PROCESSED, FAILED.

Parameters​

NameInTypeRequiredDescription
conversionOrderIdpathstringYesThe conversion order ID

Response​

Returns the full conversion order with timing details.

{
  "conversionOrderId": {"id": "b26207dc-..."},
  "documentId": {"id": "b64_..."},
  "currentState": "PROCESSED",
  "format": "pdf",
  "queuedDate": "2026-03-16T14:00:00Z",
  "processedDate": "2026-03-16T14:00:02Z",
  "processingTime": 2000,
  "queuedTime": 50,
  "errorMessage": null
}

Errors​

StatusDescription
200Conversion order returned
404Conversion order not found
500Internal server error

Example request​

curl http://localhost:8761/conversions/b26207dc-22b8-4cc4-a448-9b377ad5b706

Example response​

{
  "conversionOrderId": {"id": "b26207dc-..."},
  "documentId": {"id": "b64_..."},
  "currentState": "PROCESSED",
  "format": "pdf",
  "queuedDate": "2026-03-16T14:00:00Z",
  "processedDate": "2026-03-16T14:00:02Z",
  "processingTime": 2000,
  "queuedTime": 50,
  "errorMessage": null
}

Cancel a conversion​

DELETE /conversions/{conversionOrderId}

Cancels and removes a specific conversion order.

Parameters​

NameInTypeRequiredDescription
conversionOrderIdpathstringYesThe conversion order ID

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200Conversion cancelled
404Conversion order not found
500Internal server error

Example request​

curl -X DELETE http://localhost:8761/conversions/b26207dc-22b8-4cc4-a448-9b377ad5b706

Delete all conversion orders​

DELETE /conversions

Deletes all conversion orders tracked by the broker.

Parameters​

None.

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200All conversions deleted
500Internal server error

Example request​

curl -X DELETE http://localhost:8761/conversions

Comparison operations​

Queue a comparison​

POST /comparisons

Compares two documents asynchronously using image-based comparison.

Parameters​

NameInTypeRequiredDescription
Content-TypeheaderstringYesMust be application/json

Request body:

{
  "leftDocumentId": {"id": "b64_doc1"},
  "rightDocumentId": {"id": "b64_doc2"},
  "fuzz": 10,
  "highlightColor": "#FF0000",
  "lowlightColor": "#00FF00"
}

All fields except leftDocumentId and rightDocumentId are optional. fuzz controls the sensitivity of image comparison. highlightColor and lowlightColor set the colors for differences.

Response​

Returns the comparison order ID for polling.

{
  "comparisonOrderId": {"id": "d8fcc984-a163-4d89-8735-30583fb8f829"}
}

Errors​

StatusDescription
200Comparison queued
400Bad request (missing document IDs)
404One or both documents not found
500Internal server error

Example request​

curl -X POST http://localhost:8761/comparisons \
  -H "Content-Type: application/json" \
  -d '{"leftDocumentId": {"id": "b64_doc1"}, "rightDocumentId": {"id": "b64_doc2"}}'

Example response​

{
  "comparisonOrderId": {"id": "d8fcc984-a163-4d89-8735-30583fb8f829"}
}

Poll comparison status​

GET /comparisons/{comparisonOrderId}

Returns the current status of a comparison order.

Parameters​

NameInTypeRequiredDescription
comparisonOrderIdpathstringYesThe comparison order ID
timeoutMsqueryintegerNoMaximum wait time (ms) before returning the current status

Response​

Returns the full comparison order including result document ID on completion.

{
  "comparisonOrderId": {"id": "d8fcc984-..."},
  "leftDocumentId": {"id": "b64_doc1"},
  "rightDocumentId": {"id": "b64_doc2"},
  "targetDocumentId": {"id": "b64_result"},
  "currentState": "PROCESSED",
  "fuzz": 10,
  "highlightColor": "#FF0000",
  "lowlightColor": "#00FF00",
  "queuedDate": "2026-03-16T14:28:52Z",
  "processedDate": "2026-03-16T14:28:55Z",
  "processingTime": 3000,
  "errorMessage": null
}

Errors​

StatusDescription
200Comparison order returned
404Comparison order not found
500Internal server error

Example request​

curl http://localhost:8761/comparisons/d8fcc984-a163-4d89-8735-30583fb8f829

Example response​

{
  "comparisonOrderId": {"id": "d8fcc984-..."},
  "leftDocumentId": {"id": "b64_doc1"},
  "rightDocumentId": {"id": "b64_doc2"},
  "targetDocumentId": {"id": "b64_result"},
  "currentState": "PROCESSED",
  "fuzz": 10,
  "highlightColor": "#FF0000",
  "lowlightColor": "#00FF00",
  "queuedDate": "2026-03-16T14:28:52Z",
  "processedDate": "2026-03-16T14:28:55Z",
  "processingTime": 3000,
  "errorMessage": null
}

Get comparison differences​

GET /difference

Returns detailed text differences between two documents.

Parameters​

NameInTypeRequiredDescription
leftDocumentIdquerystringYesFirst document ID
rightDocumentIdquerystringYesSecond document ID

Response​

Returns text changes with their positions and change fragments.

{
  "leftDocumentId": {"id": "b64_doc1"},
  "rightDocumentId": {"id": "b64_doc2"},
  "textChanges": [
    {
      "changeType": "MODIFIED",
      "left": {"text": "old text", "pageNumber": 0, "position": {"x": 36.0, "y": 41.6, "w": 60.0, "h": 12.0}},
      "right": {"text": "new text", "pageNumber": 0, "position": {"x": 36.0, "y": 41.6, "w": 60.0, "h": 12.0}},
      "fragments": [
        {"text": "old", "type": "DELETED", "pageNumber": 0, "endOfLine": false},
        {"text": "new", "type": "INSERTED", "pageNumber": 0, "endOfLine": false}
      ]
    }
  ]
}

Errors​

StatusDescription
200Differences returned
400Missing required document IDs
404One or both documents not found
500Internal server error

Example request​

curl "http://localhost:8761/difference?leftDocumentId=b64_doc1&rightDocumentId=b64_doc2"

Example response​

{
  "leftDocumentId": {"id": "b64_doc1"},
  "rightDocumentId": {"id": "b64_doc2"},
  "textChanges": [
    {
      "changeType": "MODIFIED",
      "left": {"text": "old text", "pageNumber": 0, "position": {"x": 36.0, "y": 41.6, "w": 60.0, "h": 12.0}},
      "right": {"text": "new text", "pageNumber": 0, "position": {"x": 36.0, "y": 41.6, "w": 60.0, "h": 12.0}},
      "fragments": [
        {"text": "old", "type": "DELETED", "pageNumber": 0, "endOfLine": false},
        {"text": "new", "type": "INSERTED", "pageNumber": 0, "endOfLine": false}
      ]
    }
  ]
}

Transformation operations​

Queue a transformation​

POST /transformations

Submits a document transformation (merge, split, reorder, redact).

Parameters​

NameInTypeRequiredDescription
Content-TypeheaderstringYesMust be application/json

Request body:

{
  "format": "pdf",
  "transformationDetails": [
    {
      "documentTitle": "Merged document",
      "transformationElements": [
        {
          "documentId": {"id": "b64_doc1"},
          "documentTitle": "Part 1",
          "pagesSelectionList": [{"minPage": 0, "maxPage": 2}]
        },
        {
          "documentId": {"id": "b64_doc2"},
          "documentTitle": "Part 2",
          "pagesSelectionList": [{"minPage": 0, "maxPage": 5}]
        }
      ]
    }
  ],
  "annotations": {"annotations": []}
}

Response​

Returns the transformation order ID for polling.

{
  "transformationOrderId": {"id": "abc123-def456"}
}

Errors​

StatusDescription
200Transformation queued
400Bad request (invalid body or format)
404One or more documents not found
500Internal server error

Example request​

curl -X POST http://localhost:8761/transformations \
  -H "Content-Type: application/json" \
  -d '{
    "format": "pdf",
    "transformationDetails": [
      {
        "documentTitle": "Merged document",
        "transformationElements": [
          {
            "documentId": {"id": "b64_doc1"},
            "documentTitle": "Part 1",
            "pagesSelectionList": [{"minPage": 0, "maxPage": 2}]
          }
        ]
      }
    ],
    "annotations": {"annotations": []}
  }'

Example response​

{
  "transformationOrderId": {"id": "abc123-def456"}
}

Get all transformation orders​

GET /transformations

Returns all transformation orders currently tracked by the broker.

Parameters​

None.

Response​

Returns an array of transformation order objects with their current state.

[
  {
    "transformationOrderId": {"id": "abc123-..."},
    "currentState": "PROCESSED",
    "format": "pdf",
    "transformationResultDocumentID": {"id": "b64_result"},
    "queuedDate": "2026-03-16T14:30:00Z",
    "processedDate": "2026-03-16T14:30:05Z",
    "processingTime": 5000,
    "errorMessage": null
  }
]

Errors​

StatusDescription
200Orders returned
500Internal server error

Example request​

curl http://localhost:8761/transformations

Example response​

[
  {
    "transformationOrderId": {"id": "abc123-..."},
    "currentState": "PROCESSED",
    "format": "pdf",
    "transformationResultDocumentID": {"id": "b64_result"},
    "queuedDate": "2026-03-16T14:30:00Z",
    "processedDate": "2026-03-16T14:30:05Z",
    "processingTime": 5000,
    "errorMessage": null
  }
]

Poll transformation status​

GET /transformations/{transformationOrderId}

Returns the current status of a transformation order. Possible states: QUEUED, PROCESSING, PROCESSED, FAILED.

Parameters​

NameInTypeRequiredDescription
transformationOrderIdpathstringYesThe transformation order ID
timeoutMsqueryintegerNoMaximum wait time (ms) before returning

Response​

Returns the full transformation order with timing details and result document ID.

{
  "transformationOrderId": {"id": "abc123-..."},
  "currentState": "PROCESSED",
  "format": "pdf",
  "transformationResultDocumentID": {"id": "b64_result"},
  "queuedDate": "2026-03-16T14:30:00Z",
  "processedDate": "2026-03-16T14:30:05Z",
  "processingTime": 5000,
  "errorMessage": null
}

Errors​

StatusDescription
200Transformation order returned
404Transformation order not found
500Internal server error

Example request​

curl http://localhost:8761/transformations/abc123-def456

Example response​

{
  "transformationOrderId": {"id": "abc123-..."},
  "currentState": "PROCESSED",
  "format": "pdf",
  "transformationResultDocumentID": {"id": "b64_result"},
  "queuedDate": "2026-03-16T14:30:00Z",
  "processedDate": "2026-03-16T14:30:05Z",
  "processingTime": 5000,
  "errorMessage": null
}

Cancel a transformation​

DELETE /transformations/{transformationOrderId}

Cancels and removes a specific transformation order.

Parameters​

NameInTypeRequiredDescription
transformationOrderIdpathstringYesThe transformation order ID

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200Transformation cancelled
404Transformation order not found
500Internal server error

Example request​

curl -X DELETE http://localhost:8761/transformations/abc123-def456

Delete all transformation orders​

DELETE /transformations

Deletes all transformation orders tracked by the broker.

Parameters​

None.

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200All transformations deleted
500Internal server error

Example request​

curl -X DELETE http://localhost:8761/transformations

Annotation operations​

Annotation endpoints are at the root path /annotation. All require a documentId query parameter.

Get annotations​

GET /annotation?documentId={documentId}

Returns all annotations for a document.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringYesThe document ID

Response​

Returns an array of annotation objects with position, style, and metadata.

{
  "annotations": [
    {
      "id": {"id": "annot-001"},
      "type": "Highlight",
      "page": 0,
      "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0},
      "color": {"r": 255, "g": 255, "b": 0},
      "opacity": 0.5,
      "creator": "john.doe",
      "subject": "highlight",
      "date": "2026-03-16T10:00:00Z",
      "creationDate": "2026-03-16T10:00:00Z",
      "documentId": {"id": "b64_..."},
      "flags": {"hidden": false, "readonly": false, "locked": false, "print": false}
    }
  ]
}

Errors​

StatusDescription
200Annotations returned
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/annotation?documentId=b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"

Example response​

{
  "annotations": [
    {
      "id": {"id": "annot-001"},
      "type": "Highlight",
      "page": 0,
      "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0},
      "color": {"r": 255, "g": 255, "b": 0},
      "opacity": 0.5,
      "creator": "john.doe",
      "subject": "highlight",
      "date": "2026-03-16T10:00:00Z",
      "creationDate": "2026-03-16T10:00:00Z",
      "documentId": {"id": "b64_..."},
      "flags": {"hidden": false, "readonly": false, "locked": false, "print": false}
    }
  ]
}

Create annotations​

PUT /annotation?documentId={documentId}

Creates new annotations for a document. The request body is an Annotations object.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringYesThe document ID
Content-TypeheaderstringYesMust be application/json

Response​

Returns 200 OK on success.

Errors​

StatusDescription
200Annotations created
400Bad request (invalid annotation data)
404Document not found
500Internal server error

Example request​

curl -X PUT "http://localhost:8761/annotation?documentId=b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw" \
  -H "Content-Type: application/json" \
  -d '{"annotations": [{"type": "Highlight", "page": 0, "position": {"x": 100, "y": 200, "w": 150, "h": 20}}]}'

Update annotations​

POST /annotation?documentId={documentId}

Updates existing annotations for a document.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringYesThe document ID
Content-TypeheaderstringYesMust be application/json

Response​

Returns 200 OK on success.

Errors​

StatusDescription
200Annotations updated
400Bad request (invalid annotation data)
404Document not found
500Internal server error

Example request​

curl -X POST "http://localhost:8761/annotation?documentId=b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw" \
  -H "Content-Type: application/json" \
  -d '{"annotations": [{"id": {"id": "annot-001"}, "type": "Highlight", "page": 0, "position": {"x": 110, "y": 200, "w": 150, "h": 20}}]}'

Delete annotations​

DELETE /annotation?documentId={documentId}

Deletes annotations from a document. The request body specifies which annotations to delete.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringYesThe document ID
Content-TypeheaderstringYesMust be application/json

Response​

Returns 200 OK on success.

Errors​

StatusDescription
200Annotations deleted
400Bad request (invalid annotation data)
404Document not found
500Internal server error

Example request​

curl -X DELETE "http://localhost:8761/annotation?documentId=b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw" \
  -H "Content-Type: application/json" \
  -d '{"annotations": [{"id": {"id": "annot-001"}}]}'

Get annotation creation policy​

GET /annotation/policy?documentId={documentId}

Returns the annotation creation policy for a document: what the user is allowed to create, available templates, security levels, and redaction reasons.

Parameters​

NameInTypeRequiredDescription
documentIdquerystringYesThe document ID

Response​

Returns the full policy including creation rules, templates, security levels, and redaction reasons.

{
  "canCreateAnnotations": true,
  "textAnnotationsSupportHtml": true,
  "textAnnotationsSupportReply": true,
  "textAnnotationsSupportStatus": true,
  "textAnnotationsCommentSupportReply": true,
  "annotationsSupportSecurity": false,
  "availableSecurityLevels": [
    {
      "symbolicName": "private",
      "localizedDisplayNames": {"fr": "Prive", "en": "Private"}
    }
  ],
  "annotationTemplateCatalog": {
    "annotationTemplates": [
      {
        "name": "Urgent",
        "annotationType": "Stamp",
        "contentTemplate": "Urgent",
        "annotationStyle": {"fontColor": "#e50000", "fontSize": 30, "rotation": 350}
      }
    ],
    "waterMarkTemplates": [
      {
        "name": "CONFIDENTIAL",
        "annotationType": "Stamp",
        "contentTemplate": "CONFIDENTIAL"
      }
    ]
  },
  "annotationCreationRuleCatalog": {
    "annotationCreationRules": [
      {
        "ruleId": "annotationCreationRuleRedactMailsAllPages",
        "ruleName": "Redact all e-mail addresses",
        "annotationTemplate": {"annotationType": "RedactText"},
        "searchOptions": {"searchText": "^\\w+@\\w+\\.\\w+$", "regex": true, "searchAction": "ALL_PAGES"}
      }
    ]
  },
  "availableRedactReasons": [
    {
      "symbolicName": "(b)(1)",
      "displayName": {"en": "Information that is classified to protect national security."}
    }
  ],
  "defaultRedactReasons": null
}

Errors​

StatusDescription
200Policy returned
404Document not found
500Internal server error

Example request​

curl "http://localhost:8761/annotation/policy?documentId=b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"

Example response​

{
  "canCreateAnnotations": true,
  "textAnnotationsSupportHtml": true,
  "textAnnotationsSupportReply": true,
  "textAnnotationsSupportStatus": true,
  "textAnnotationsCommentSupportReply": true,
  "annotationsSupportSecurity": false,
  "availableSecurityLevels": [
    {
      "symbolicName": "private",
      "localizedDisplayNames": {"fr": "Prive", "en": "Private"}
    }
  ],
  "annotationTemplateCatalog": {
    "annotationTemplates": [
      {
        "name": "Urgent",
        "annotationType": "Stamp",
        "contentTemplate": "Urgent",
        "annotationStyle": {"fontColor": "#e50000", "fontSize": 30, "rotation": 350}
      }
    ],
    "waterMarkTemplates": [
      {
        "name": "CONFIDENTIAL",
        "annotationType": "Stamp",
        "contentTemplate": "CONFIDENTIAL"
      }
    ]
  },
  "annotationCreationRuleCatalog": {
    "annotationCreationRules": [
      {
        "ruleId": "annotationCreationRuleRedactMailsAllPages",
        "ruleName": "Redact all e-mail addresses",
        "annotationTemplate": {"annotationType": "RedactText"},
        "searchOptions": {"searchText": "^\\w+@\\w+\\.\\w+$", "regex": true, "searchAction": "ALL_PAGES"}
      }
    ]
  },
  "availableRedactReasons": [
    {
      "symbolicName": "(b)(1)",
      "displayName": {"en": "Information that is classified to protect national security."}
    }
  ],
  "defaultRedactReasons": null
}

Convert annotations between formats​

POST /annotations/conversion

Converts annotations between FDF and XFDF formats.

Parameters​

NameInTypeRequiredDescription
sourceTypequerystringYesSource format: FDF or XFDF
targetTypequerystringYesTarget format: FDF or XFDF
documentIdquerystringYesThe document ID
AcceptheaderstringYesExpected response content type
Content-TypeheaderstringYesMust be application/octet-stream

Response​

Annotation data in the target format.

Errors​

StatusDescription
200Conversion successful
400Bad request (invalid source/target type)
404Document not found
500Internal server error

Example request​

curl -X POST "http://localhost:8761/annotations/conversion?sourceType=XFDF&targetType=FDF&documentId=b64_..." \
  -H "Content-Type: application/octet-stream" \
  -H "Accept: application/octet-stream" \
  --data-binary @annotations.xfdf

Document loading​

Load document from URL​

POST /accessor/load

Loads a document from a URL or file path. The request body is a DocumentAccessor object.

Parameters​

NameInTypeRequiredDescription
Content-TypeheaderstringYesMust be application/json

Response​

Returns the document ID of the loaded document.

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

Errors​

StatusDescription
200Document loaded
400Bad request (invalid accessor)
500Internal server error (URL unreachable, etc.)

Example request​

curl -X POST http://localhost:8761/accessor/load \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/document.pdf"}'

Example response​

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

Provider operations​

These endpoints are used by the React UI to open documents through REST providers and manage annotations on provider-loaded documents. For the provider-side API contract, see Provider API.

Open document through provider​

POST /registry/documents

Opens a document through a registered REST provider. The broker resolves the provider from the X-Provider-ID header, forwards the request parameters to the provider's GET /documents endpoint, caches the result, and returns a DocumentId.

Parameters​

NameInTypeRequiredDescription
X-Provider-IDheaderstringNoProvider name (e.g., filenet, alfresco). If omitted, the broker uses the registry.default-provider configuration value
Content-TypeheaderstringYesMust be application/octet-stream (or the actual document mime type) or application/json for composite document

Request body: Form-encoded parameters specific to the provider (e.g., id=DOC123&objectStoreName=OS1 for FileNet).

Response​

Returns a DocumentId object.

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

Errors​

StatusDescription
200Document opened
400Bad request (missing or invalid parameters)
403Access denied by the provider
404Document not found in the provider
500Internal server error
502Provider unreachable

Example request​

curl -X POST "http://broker:8761/registry/documents" \
  -H "X-Provider-ID: filenet" \
  -d "id=DOC123&objectStoreName=OS1"

Example response​

{
  "id": "b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw"
}

List annotation IDs​

GET /documents/{documentId}/annotations/ids

Retrieves the list of annotation identifiers for a document opened via POST /registry/documents. The broker proxies the request to the provider's GET /annotations/ids endpoint.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesInternal document ID returned by POST /registry/documents

Response​

JSON array of annotation ID objects.

[
  {"id": "annot-001"},
  {"id": "annot-002"}
]

Errors​

StatusDescription
200Annotation IDs returned
403Access denied by the provider
404Document not found
500Internal server error
502Provider unreachable

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/annotations/ids

Example response​

[
  {"id": "annot-001"},
  {"id": "annot-002"}
]

Get annotation​

GET /documents/{documentId}/annotations/{annotationId}

Retrieves a single annotation. The broker proxies the request to the provider and applies annotation position transformations when the document has a composite layout.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesInternal document ID
annotationIdpathstringYesAnnotation identifier

Response​

Annotation object.

{
  "id": {"id": "annot-001"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Errors​

StatusDescription
200Annotation returned
403Access denied by the provider
404Document or annotation not found
500Internal server error
502Provider unreachable

Example request​

curl http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/annotations/annot-001

Example response​

{
  "id": {"id": "annot-001"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Create annotation​

POST /documents/{documentId}/annotations

Creates a new annotation. The broker applies position transformations and proxies the request to the provider's POST /annotations endpoint.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesInternal document ID

Request body: Annotation object (JSON).

Response​

The created annotation object.

{
  "id": {"id": "annot-003"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Errors​

StatusDescription
200Annotation created
400Bad request (invalid annotation data)
403Access denied by the provider
404Document not found
500Internal server error
502Provider unreachable

Example request​

curl -X POST http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/annotations \
  -H "Content-Type: application/json" \
  -d '{"type": "Highlight", "page": 0, "position": {"x": 100, "y": 200, "w": 150, "h": 20}}'

Example response​

{
  "id": {"id": "annot-003"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 100.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Update annotation​

PUT /documents/{documentId}/annotations/{annotationId}

Updates an existing annotation.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesInternal document ID
annotationIdpathstringYesAnnotation identifier

Request body: Updated annotation object (JSON).

Response​

The updated annotation object.

{
  "id": {"id": "annot-001"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 110.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Errors​

StatusDescription
200Annotation updated
400Bad request (invalid annotation data)
403Access denied by the provider
404Document or annotation not found
500Internal server error
502Provider unreachable

Example request​

curl -X PUT http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/annotations/annot-001 \
  -H "Content-Type: application/json" \
  -d '{"type": "Highlight", "page": 0, "position": {"x": 110, "y": 200, "w": 150, "h": 20}}'

Example response​

{
  "id": {"id": "annot-001"},
  "type": "Highlight",
  "page": 0,
  "position": {"x": 110.0, "y": 200.0, "w": 150.0, "h": 20.0}
}

Delete annotation​

DELETE /documents/{documentId}/annotations/{annotationId}

Deletes an annotation.

Parameters​

NameInTypeRequiredDescription
documentIdpathstringYesInternal document ID
annotationIdpathstringYesAnnotation identifier

Response​

Returns 200 OK with no body.

Errors​

StatusDescription
200Annotation deleted
403Access denied by the provider
404Document or annotation not found
500Internal server error
502Provider unreachable

Example request​

curl -X DELETE http://localhost:8761/documents/b64_NDNiMmI0NjctZGZlOS00MjgzLWExZWYtMjVkNGIyNTQ5Nzgw/annotations/annot-001
note

These annotation endpoints only apply to documents opened via POST /registry/documents. For documents opened via POST /documents, use the annotation endpoints documented above.

Administration​

Health readiness​

GET /health/readiness

Returns 200 OK with an empty body when the broker is ready to serve requests. Use this endpoint for container health checks and load balancer probes.

Parameters​

None.

Response​

Empty body with 200 OK status.

Errors​

StatusDescription
200Broker is ready
503Broker is not ready

Example request​

curl http://localhost:8761/health/readiness

Health records (HTML)​

GET /health/records

Returns an HTML dashboard showing the health status of all registered microservices.

Parameters​

None.

Response​

HTML page (Content-Type: text/html).

Errors​

StatusDescription
200Health dashboard returned
500Internal server error

Example request​

curl http://localhost:8761/health/records

Health records (raw)​

GET /health/records/raw

Returns raw health record data as JSON.

Parameters​

None.

Response​

Returns service states with their current status.

{
  "serviceStates": {
    "document-converter": {"serviceStatus": "UP", "restarted": false},
    "document-renderer": {"serviceStatus": "UP", "restarted": false},
    "document-text-handler": {"serviceStatus": "UP", "restarted": false}
  }
}

Errors​

StatusDescription
200Health records returned
500Internal server error

Example request​

curl http://localhost:8761/health/records/raw

Example response​

{
  "serviceStates": {
    "document-converter": {"serviceStatus": "UP", "restarted": false},
    "document-renderer": {"serviceStatus": "UP", "restarted": false},
    "document-text-handler": {"serviceStatus": "UP", "restarted": false}
  }
}

Get version​

GET /version

Returns installed tool versions for all components in the ARender stack.

Parameters​

None.

Response​

Returns a key-value map of tool names and their versions.

{
  "Wkhtmltopdf": "0.12.6",
  "FFmpeg": "4.2.3",
  "LibreOffice": "25.8.2",
  "ImageMagick": "7.1.1-21",
  "ARender": "2026.0.0-rc0"
}

Errors​

StatusDescription
200Versions returned
500Internal server error

Example request​

curl http://localhost:8761/version

Example response​

{
  "Wkhtmltopdf": "0.12.6",
  "FFmpeg": "4.2.3",
  "LibreOffice": "25.8.2",
  "ImageMagick": "7.1.1-21",
  "ARender": "2026.0.0-rc0"
}

Get metadata​

GET /metadata

Returns broker metadata as a key-value map.

Parameters​

None.

Response​

Key-value map of metadata properties.

{
  "broker.version": "2026.0.0-rc0",
  "broker.uptime": "3h 15m"
}

Errors​

StatusDescription
200Metadata returned
500Internal server error

Example request​

curl http://localhost:8761/metadata

Get weather score​

GET /weather

Returns a performance score as a floating-point number (lower is better). This endpoint measures the current load on the broker.

Parameters​

None.

Response​

A floating-point number representing the current performance score.

3.15

Errors​

StatusDescription
200Score returned
500Internal server error

Example request​

curl http://localhost:8761/weather

Example response​

3.15

Admin UI​

GET /admin

Browser-based administration interface for uploads, conversions, and transformations. Open this URL in a browser.

Parameters​

None.

Response​

HTML page (Content-Type: text/html).

Example request​

Open in a browser:

http://localhost:8761/admin

Next steps​

Last updated on