Skip to main content
Version: v2026.0.0

Servlet API Reference

The ARender Web UI exposes a set of HTTP servlet endpoints for document operations, annotation export, printing, monitoring, and session management.

Base URL: http://<arender_host>/arendergwt/

Replace <arender_host> with your ARender HMI host and port.


Document operations

Upload document by reference

GET /arendergwt/uploadServlet

Load a document into ARender by passing its connector-level document ID. The server fetches the document and makes it available for viewing.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID to upload

Response

Returns the new UUID created from the document ID. The document is downloaded to the server and made available in ARender.

Errors

StatusDescription
200Document uploaded successfully
400Missing or invalid uuid parameter
500Internal server error during document retrieval

Example request

curl -X GET 'http://<arender_host>/arendergwt/uploadServlet?uuid=docUUID'

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Upload document by file

POST /arendergwt/uploadServlet

Upload a file directly to ARender via multipart form data. The server stores the file and returns a UUID for subsequent operations.

Parameters

NameInTypeRequiredDescription
filebodyfileYesThe file to upload (multipart/form-data)

Response

Returns the new UUID assigned to the uploaded document.

Errors

StatusDescription
200File uploaded successfully
400Missing file in request body
500Internal server error during file processing

Example request

curl -X POST -H "Content-Type: multipart/form-data" \
-F "file=@yourFile.pdf" \
"http://<arender_host>/arendergwt/uploadServlet"

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Download document

GET /arendergwt/downloadServlet

Download a document in its original format, as a rendered PDF, or as a ZIP archive.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
sourceIdquerystringNoInitial document ID (useful if the document ID has been transformed)
titlequerystringNoTitle of the downloaded file
typequerystringNoDownload type: INITIAL (original format, no annotations), RENDERED (PDF, MP4, or TIFF), COMPRESSED (ZIP)

Response

The document file in the requested format, with the filename set according to the title parameter.

Errors

StatusDescription
200Document returned successfully
400Missing or invalid parameters
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/downloadServlet?uuid=docUUID&title=DocumentTitle&type=INITIAL'

Example response

Binary file content in the requested format.


Download document as Base64

GET /arendergwt/downloadBase64EncodedDocument

Download a document encoded in base64. The content must be decoded before use.

Parameters

None.

Response

The document content encoded as a base64 string.

Errors

StatusDescription
200Base64-encoded content returned
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/downloadBase64EncodedDocument'

Example response

JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwov...

Download document with annotations

GET /arendergwt/downloadDocumentWithAnnotations

Download a PDF document with annotations either burned into the page content or embedded as editable FDF annotation objects.

Parameters

NameInTypeRequiredDescription
operationNamequerystringYesrenderAnnotations (annotations flattened onto the PDF) or renderFDFAnnotations (annotations as editable FDF objects)

Response

A PDF file with annotations applied according to the specified operation.

Errors

StatusDescription
200Annotated PDF returned
400Missing or invalid operationName
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/downloadDocumentWithAnnotations?operationName=renderAnnotations'

Example response

Binary PDF content with annotations.


Download comparison results

GET /arendergwt/downloadServlet/mergedWithCompareResult

Download the result of comparing two documents. Common text is highlighted in green and differing text is highlighted in red.

Parameters

NameInTypeRequiredDescription
leftquerystringYesUUID of the first document
rightquerystringYesUUID of the second document

Response

A document where common text is highlighted in green and differing text is highlighted in red.

Errors

StatusDescription
200Comparison document returned
400Missing left or right parameter
404One or both documents not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/downloadServlet/mergedWithCompareResult?left=doc1UUID&right=doc2UUID'

Example response

Binary document content with highlighted differences.


Merge documents

POST /arendergwt/mergeDocumentsServlet

Merge multiple documents into a single PDF. Also accepts GET requests with query parameters.

Parameters

NameInTypeRequiredDescription
urlquery/bodystringYes (repeatable)URL or connector reference for each document to merge. Repeat this parameter for each document.

Response

JSON containing the UUID and page count of the merged document. The merged document can then be viewed at http://<arender_host>/?uuid=<merged_uuid>.

Errors

StatusDescription
200Documents merged successfully
400Missing or invalid url parameters
500Internal server error during merge

Example request

# POST
curl --data "url=../../samples/arender.pdf&url=../../samples/fw4.pdf" \
http://<arender_host>/arendergwt/mergeDocumentsServlet

# GET
curl -X GET 'http://<arender_host>/arendergwt/mergeDocumentsServlet?url=../../samples/arender.pdf&url=../../samples/fw4.pdf'

Example response

{
"uuid": "b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0",
"nbPages": "32"
}

Create composite document

POST /arendergwt/compositeAccessorServlet

Create a composite (folder) document from a JSON structure describing nested document references. This is useful for building virtual folder trees that exceed URL length limits.

note

This endpoint requires sticky sessions if a load balancer is in front of the ARender HMI servers.

Parameters

NameInTypeRequiredDescription
Request bodybodyJSONYesA JSON object describing the folder structure (see below)

The request body uses Content-Type: application/json and contains:

  • title (optional) -- folder or document title
  • queryUrl (optional) -- a valid loadingQuery?<params> string (makes this node a document)
  • references (optional) -- array of child nodes (makes this node a folder)

queryUrl and references are mutually exclusive; queryUrl takes precedence.

Response

The ARender document ID of the created composite document.

Errors

StatusDescription
200Composite document created
400Invalid JSON structure
500Internal server error

Example request

curl -X POST http://<arender_host>/arendergwt/compositeAccessorServlet \
-d @composite.json --header "Content-Type: application/json"

With composite.json:

{
"title": "test_Container",
"references": [
{ "queryUrl": "loadingQuery?url=http://example.com/doc1.pdf" },
{ "queryUrl": "loadingQuery?url=http://example.com/doc2.pdf" },
{
"title": "subfolder",
"references": [
{ "queryUrl": "loadingQuery?url=http://example.com/doc3.pdf" }
]
}
]
}

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Retrieve composite document

GET /arendergwt/compositeAccessorServlet

Retrieve or initialize a composite document container. Returns a new document ID that can be used with the PUT endpoint to incrementally add documents.

Parameters

NameInTypeRequiredDescription
containerTitleCompositequerystringNoComposite document title (defaults to "Document container")

Response

A new document ID that can be used in subsequent requests.

Errors

StatusDescription
200Composite container created
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/compositeAccessorServlet?containerTitleComposite=myTitle'

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Add document to composite

PUT /arendergwt/compositeAccessorServlet

Incrementally add documents to a composite container created via GET, then finalize it.

Parameters

NameInTypeRequiredDescription
documentIdCompositequerystringYesThe document ID of the composite container (returned by GET)
finalquerystringNoIf present, finalizes the container (loads it into the session and invalidates the cache entry). If absent, adds the parsed document URL to the container's children.
containerTitleCompositequerystringNoTitle for the child document being added
mimeTypeCompositequerystringNoMIME type hint for the child document
Request bodybodystringNoURL-encoded document URL to add

Response

The composite document ID.

Errors

StatusDescription
200Document added or container finalized
400Missing documentIdComposite parameter
404Composite container not found
500Internal server error

Example request

# Add a document to the container
curl -X PUT 'http://<arender_host>/arendergwt/compositeAccessorServlet?documentIdComposite=compositeUUID&final=true&containerTitleComposite=Doc1' \
--data-urlencode "url=http://example.com/doc1.pdf"

# Finalize the container (no 'final' parameter omitted — pass 'final' with any value)
curl -X PUT 'http://<arender_host>/arendergwt/compositeAccessorServlet?documentIdComposite=compositeUUID&final=done'

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Prepare external document opening

GET /arendergwt/openExternalDocument

Generate an encoded UUID from URL parameters, suitable for opening a document via a connector.

Parameters

NameInTypeRequiredDescription
urlquerystringYesThe document URL

Response

An encoded UUID (base64 or encrypted, depending on configuration).

The encoding mode is controlled by the property:

arender.documentid.generator.beanName=documentIdGenerator
# Use encryptedDocumentIdGenerator for encrypted UUIDs

Errors

StatusDescription
200Encoded UUID returned
400Missing url parameter
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/openExternalDocument?url=docURL'

Example response

b64_NWNjODk3MmQtMjJhOC00YzM3LWE4YjItNjZiMTkzOGFkMzU0

Evict document from cache

GET /arendergwt/evictDocument

Remove a document from both memory cache and filesystem cache. The document is no longer accessible on the server after eviction.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID to evict

Response

The document is removed from all caches.

Errors

StatusDescription
200Document evicted successfully
400Missing uuid parameter
404Document not found in cache
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/evictDocument?uuid=doc1UUID'

Example response

OK

Document structure

Get document layout

GET /arendergwt/documentLayout

Retrieve the structure of a document as JSON, including page dimensions, MIME type, and title.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID

Response

JSON describing the document structure with page dimensions, MIME type, and document title.

Errors

StatusDescription
200Layout returned successfully
400Missing uuid parameter
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/documentLayout?uuid=doc1UUID'

Example response

{
"type": "com.arondor.viewer.client.api.document.DocumentPageLayout",
"documentId": { "id": "doc1UUID" },
"documentTitle": "title.pdf",
"mimeType": "application/pdf",
"pageDimensionsList": [
{
"width": 720.0,
"height": 405.0,
"rotation": 0,
"dpi": 0,
"pageLayers": null
}
]
}

Get flat document layout

GET /arendergwt/flatDocumentLayout

Retrieve a flat list of all pages across child documents, without preserving the tree structure.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID

Response

A JSON array of page identifiers.

Errors

StatusDescription
200Flat layout returned successfully
400Missing uuid parameter
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/flatDocumentLayout?uuid=docuuid'

Example response

[
"b64_bG9jYWxl.../1/1/1/1|0|612.0",
"b64_bG9jYWxl.../1/1/1/2|0|612.0",
"b64_bG9jYWxl.../1/2|0|612.0"
]

Get page content

GET /arendergwt/pageContent

Retrieve the text content and layout information for a specific page, including text positions, fonts, sizes, and hyperlink information.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
pagePositionqueryintegerYesPage number (zero-based)

Response

JSON with text positions, fonts, sizes, and hyperlink information for the specified page.

Errors

StatusDescription
200Page content returned
400Missing or invalid parameters
404Document or page not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/pageContent?uuid=docuuid&pagePosition=3'

Example response

{
"pageNumber": 3,
"positionTextList": [
{
"pageNumber": 3,
"position": { "x": 124.68, "y": 204.1, "w": 113.35, "h": 34.0 },
"text": "Features",
"individualWidths": [15.07, 15.8, 15.6, 10.96, 15.77, 10.9, 15.8, 13.45],
"fontSize": 27.0,
"font": "BCDIEE+Oxygen bold",
"paragraphId": 0,
"rightToLeftText": false,
"startTime": -1.0
}
],
"imageHyperlinkPositionList": []
}

Page imaging

Get page image

GET /arendergwt/imageServlet

Retrieve a rendered image of a specific document page at the requested resolution.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
pagePositionqueryintegerYesPage number
descqueryintegerYesImage size in pixels

Response

The page rendered as an image (binary content).

Errors

StatusDescription
200Page image returned
400Missing or invalid parameters
404Document or page not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/imageServlet?uuid=docUUID&pagePosition=0&desc=1024'

Example response

Binary image content (PNG/JPEG).


Crop page image

GET /arendergwt/cropImageServlet

Retrieve a cropped region of a document page as an image with descriptive text for saving.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
localequerystringYesLanguage of the text
pagePositionqueryintegerYesPage number
descquerystringYesCrop settings (size, position, color, etc.)

Response

An image of the cropped region.

Errors

StatusDescription
200Cropped image returned
400Missing or invalid parameters
404Document or page not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/cropImageServlet?uuid=docUUID&locale=en&pagePosition=0&desc=size'

Example response

Binary image content.


Annotation export

Download XFDF/FDF annotations

GET /arendergwt/servletXFDFAnnotations

Download annotations for a document in XFDF or FDF format.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
typequerystringNoFile type: XFDF (default) or FDF

Response

The annotation file in the requested format.

Errors

StatusDescription
200Annotation file returned
400Missing uuid parameter
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/servletXFDFAnnotations?uuid=docUUID&type=XFDF'

Example response

<?xml version="1.0" encoding="UTF-8"?>
<ns0:xfdf xmlns:ns0="http://ns.adobe.com/xfdf/">
<ns0:annots>
<ns0:highlight color="#273746" flags="obfuscate"
name="c553fe65-a3a0-4628-b396-1201bfea6285" page="1"
rect="153.26,334.42,264.57,374.02" title="admin"
creationdate="D:20221214090312+00'00'" opacity="1.0"
coords="153.26,374.02,264.57,374.02,153.26,334.42,264.57,334.42"/>
<ns0:circle color="#EAF39C" flags=""
name="cfdbee9c-dce1-4e62-bc10-55ab1554476b" page="0"
rect="82.03,218.50,183.40,337.68" title="Unknown"
creationdate="D:20221228084701+00'00'" opacity="0.7"
interior-color="#EAF39C" width="0.0" style="solid"/>
</ns0:annots>
</ns0:xfdf>

Upload XFDF annotations

POST /arendergwt/servletXFDFAnnotations

Upload annotations in XFDF or FDF format to apply to a document. If the uploaded file is in FDF format, it will be converted to XFDF automatically.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID to apply annotations to
filebodyfileYesThe XFDF or FDF file to upload (multipart/form-data)

Response

Annotations are applied to the specified document.

Errors

StatusDescription
200Annotations uploaded successfully
400Missing uuid or file
404Document not found
500Internal server error

Example request

curl -X POST -H "Content-Type: multipart/form-data" \
-F "file=@annotations.xfdf" \
"http://<arender_host>/arendergwt/servletXFDFAnnotations?uuid=docUUID"

Example response

OK

Printing

GET /arendergwt/printServlet

Display an HTML print-preview page for selected document pages, with a confirmation dialog for the user.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
descquerystringYesImage description for the pages to print
pagesquerystringYesPage numbers to print (comma-separated)
imagePrintStylequerystringNoImage style for the printed pages

Response

An HTML page with a print preview and confirmation dialog.

Errors

StatusDescription
200Print preview page returned
400Missing or invalid parameters
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/printServlet?uuid=docUUID&desc=description&pages=1,2,3&imagePrintStyle=style'

Example response

HTML content with print preview.


GET /arendergwt/printPage

Render specific document pages as an HTML file suitable for browser printing.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID
nbPagesqueryintegerYesNumber of pages to print
renditionPrintWidthqueryintegerYesImage width in the rendition (pixels)
browserPrintWidthqueryintegerYesImage width displayed in the browser (pixels)
pagequerystringYesPage numbers to print (comma-separated)

Response

An HTML file containing the rendered pages ready for printing.

Errors

StatusDescription
200Print-ready HTML returned
400Missing or invalid parameters
404Document not found
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/printPage?uuid=docUUID&nbPages=3&renditionPrintWidth=800&browserPrintWidth=600&page=1,2,3'

Example response

HTML content with rendered pages.


Monitoring and administration

Get version

GET /arendergwt/version

Retrieve the deployed ARender version string.

Parameters

None.

Response

The ARender version in plain text.

Errors

StatusDescription
200Version returned
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/version'

Example response

4.12.0.0

Get health records

GET /arendergwt/health/records

Display server health and service availability status. Returns an HTML page listing each service with its port, state, and availability.

Parameters

NameInTypeRequiredDescription
checkquerystringNoSELF (return the HTML page even if no service is available) or RENDITION (return an error if no service is available)

Response

An HTML page listing each service with its port, state, and availability.

Errors

StatusDescription
200Health records page returned
503No rendition service available (when check=RENDITION)
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/health/records?check=SELF'

Example response

HTML content with service status table.


Get Prometheus metrics

GET /arendergwt/prometheus

Expose Prometheus-compatible metrics for monitoring.

Parameters

None.

Response

Prometheus metrics in standard exposition format.

Errors

StatusDescription
200Metrics returned
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/prometheus'

Example response

# HELP arender_documents_loaded Total documents loaded
# TYPE arender_documents_loaded counter
arender_documents_loaded 142

Get server performance

GET /arendergwt/weather

Retrieve performance data for all connected rendition servers.

Parameters

NameInTypeRequiredDescription
formatquerystringNoResponse format. If empty or HTML, returns an HTML page. Any other value (e.g., JSON) returns JSON.

Response

Server performance data in the requested format.

Errors

StatusDescription
200Performance data returned
500Internal server error

Example request

# HTML format
curl -X GET 'http://<arender_host>/arendergwt/weather'

# JSON format
curl -X GET 'http://<arender_host>/arendergwt/weather?format=JSON'

Example response

HTML or JSON content with server performance metrics.


Set rendition targets

POST /arendergwt/weather

Replace the entire list of rendition server targets with a new set of addresses.

Parameters

NameInTypeRequiredDescription
Request bodybodystringYesA JSON-like list of rendition server addresses

Response

The rendition target list is replaced.

Errors

StatusDescription
200Targets replaced successfully
400Invalid request body
500Internal server error

Example request

curl -X POST -d "{[http://rendition-host:1990]}" \
'http://<arender_host>/arendergwt/weather'

Example response

OK

Add rendition targets

PUT /arendergwt/weather

Add rendition server addresses to the existing target list without replacing it.

Parameters

NameInTypeRequiredDescription
Request bodybodystringYesA JSON-like list of rendition server addresses to add

Response

The new addresses are added to the existing target list.

Errors

StatusDescription
200Targets added successfully
400Invalid request body
500Internal server error

Example request

curl -X PUT -d "{[http://new-rendition-host:1990]}" \
'http://<arender_host>/arendergwt/weather'

Example response

OK

Session management

Destroy session

GET /arendergwt/destroySession

Destroy the current user session and clear all associated ARender state. Accepts any HTTP method (GET, POST, etc.).

Parameters

None.

Response

The session is destroyed, clearing the following information:

  • user
  • userAgent
  • versionUserAgent

Errors

StatusDescription
200Session destroyed
500Internal server error

Example request

curl -X GET 'http://<arender_host>/arendergwt/destroySession'

Example response

OK

Validate token

POST /arendergwt/validateToken

Validate an authentication token sent as a cookie or POST attribute. The token must be named token.

Parameters

NameInTypeRequiredDescription
tokencookie/bodystringYesThe authentication token to validate

Response

Validation result from the configured TokenValidator implementation.

The validator class is configured via the property:

arender.server.json.load.token.validator=com.example.MyTokenValidator

The custom class must implement the TokenValidator interface and its validate method. The default validator (NoopTokenValidator) only checks that the token is not null.

Errors

StatusDescription
200Token is valid
400Token is missing or null
403Token validation failed
500Internal server error

Example request

curl -X POST 'http://<arender_host>/arendergwt/validateToken' \
-d "token=myAuthToken"

Example response

Valid

Connector-specific endpoints

Update FileNet document metadata

POST /arendergwt/updateDocumentMetadataServlet

Update IBM FileNet document metadata. The propertyKey corresponds to the FileNet symbolicName or displayName.

Parameters

NameInTypeRequiredDescription
uuidquerystringYesDocument ID of the target FileNet document
Request bodybodyJSONYesJSON mapping of metadata property names to values

The request uses Content-Type: application/json.

Response

Metadata is updated on the FileNet document.

Errors

StatusDescription
200Metadata updated successfully
400Invalid JSON or missing uuid
404Document not found
500Internal server error

Example request

curl -X POST 'http://<arender_host>/arendergwt/updateDocumentMetadataServlet?uuid=docUUID' \
-H "Content-Type: application/json" \
-d '{"DocumentTitle": "Updated Title", "Status": "Approved"}'

Example response

{
"propertyKey1": "propertyValue1",
"propertyKey2": "propertyValue2"
}