Archive Browser REST API

This page provides everything you need to understand and interact with the Archive Browser REST API

General Information

The Archive Browser provides a REST API that mirrors all capabilities of the web UI. You can use it for integrations, automated reporting, custom dashboards, and tooling built on top of the archive data.

Built-in Interactive API Tool (Swagger UI)

The Archive Browser includes a built-in Swagger UI that allows you to explore the endpoints and test API calls directly against your own server. Once the application is running, you can access these tools at:

Interactive UI: https://<host>:8443/swagger-ui/index.html
Raw OpenAPI 3.0 specification: https://<host>:8443/openapi (useful for importing into API clients like Postman)

Authentication

The Archive Browser REST API requires authentication for all data requests. You must include a valid token in the Authorization: Bearer header of your HTTP requests.

You can authenticate using two methods:

API Keys: Generated in Settings > API Keys, these act as permanent bearer tokens. By default, they do not expire; an optional expiry date can be set at creation time. This is the recommended method for long-running integrations.
Session Tokens: Short-lived JSON Web Tokens (JWT) generated by submitting your credentials to the API. For more information on how to generate them, see Authentication endpoint.

HTTP Status Codes and Error Handling

The Archive Browser REST API returns standard HTTP status codes to indicate the success or failure of an API request.

200: Success.
400: Bad request (invalid filter parameter, sort string, or date format).
401: Unauthorized (missing or invalid token).
403: Forbidden (the authenticated user does not have the required role).
404: Not found (the requested resource does not exist).
409: Conflict (upload rejected because files already exist).
500: Internal server error.

When the API returns an error (any 4xx or 5xx status code), the response body provides a consistent JSON structure to help you troubleshoot. This JSON object explicitly details the timestamp, HTTP status, error type, specific error message, and the requested path.

Using the REST API

You can interact with the REST API using command-line tools like curl or through scripting languages like Python. The following examples demonstrate how to construct endpoint URLs to perform common administrative and reporting tasks.

When testing these examples in your own environment, remember to prepend your server's base URL, for example, [https://archivebrowser.example.com](https://archivebrowser.example.com) and include your API key or session token in the Authorization: Bearer header.

List the 10 most recent failed executions: Use this endpoint to filter by status codes representing specific failures (such as 1850 and 1899) and sort by the start time in descending order.

GET /api/executions?status=1850,1899&sort=-startTime&max_results=10
Get the execution report content: Use this endpoint to retrieve the raw text of a specific report file (such as the REP execution report) for a known RunID.

GET /api/executions/1000030/reports/REP
Download all executions from the last 7 days as CSV: Use this endpoint to stream a large dataset directly to a CSV file by defining a precise timeframe and bounding the start time.

GET /api/executions/download?time_frame_from=2024.06.08%2000:00:00&time_frame_to=2024.06.15%2023:59:59&time_frame_option=start&max_results=100
Full-text search for a specific error: Use this endpoint to scan all indexed report contents for a specific text string (like "connection refused") and limit the output results.

GET /api/executions/search?q=connection+refused&max_results=20

REST API Reference

The following reference details the available endpoints for the Archive Browser REST API, organized by functional categories such as Authentication, Executions, Reports, Messages, and Archives.

Authentication

Authentication endpoints allow you to securely connect to the API before issuing any data queries.

POST /auth/token: Authenticates a user and generates a short-lived JWT token. This requires a JSON body (application/json) containing the username and password. This is the only endpoint that does not require a bearer token in the request header.

Executions

These endpoints allow you to search, filter, export, and retrieve specific execution records from the archive index.

GET /api/executions: Returns a paginated list of archived execution records. It supports filtering, sorting, and cursor-based pagination (see the parameter table below).
GET /api/executions/{run_id}: Returns the index metadata for a single execution identified by its RunID.
GET /api/executions/{run_id}/content: Returns the full archive header record for an execution, including the raw text content exactly as stored in the archive file.
GET /api/executions/{run_id}/children: Returns all immediate child task executions of a workflow (JOBP) execution.
GET /api/executions/download: Streams a CSV file containing execution records matching your specified filters. This endpoint accepts the same query parameters as the list endpoint, and the response is streamed without size limits.

List Executions Query Parameters

You can use the following parameters with the GET /api/executions endpoint to filter and sort your results:

Parameter	Type	Default Value	Description
start_at	integer	0	Zero-based page index.
start_at_run_id	integer	0	Cursor-based paging to return only executions with a RunID greater than this value.
max_results	integer	50	Page size (range: 1–100).
name	string	None	Filter by object name (case-insensitive substring match).
status	integer array	None	Filter by AE status codes (multiple values are OR'd together).
user	string	None	Filter by activating username (substring match).
department	string	None	Filter by user department (substring match).
client	string array	None	Filter by AE client numbers (multiple values are OR'd together).
a_type	string array	None	Filter by object type codes, e.g., JOBS (multiple values are OR'd together).
s_type	string array	None	Filter by object sub-type codes (multiple values are OR'd together).
host_name	string	None	Filter by agent or host name (substring match).
parent_act	string	None	Filter by parent activation name (substring match).
archive_key1	string	None	Filter by archive key 1 (substring match).
archive_key2	string	None	Filter by archive key 2 (substring match).
run_id	integer array	None	Filter by specific RunIDs.
parent_run_id	integer	None	Filter for direct children of the given parent RunID.
time_frame_from	string	1900.01.01 00:00:00	Timeframe lower bound in yyyy.MM.dd HH:mm:ss format.
time_frame_to	string	1900.01.01 00:00:00	Timeframe upper bound in yyyy.MM.dd HH:mm:ss format.
time_frame_option	string	all	Which timestamp field the timeframe applies to (activation, start, end, all).
sort	string	+runID	Comma-separated sort fields, prefixed with + for ascending or - for descending.

Reports and Comments

Use these endpoints to access the raw text output, logs, and user annotations attached to specific executions.

GET /api/executions/{run_id}/reports: Returns all report headers associated with the given execution RunID.
GET /api/executions/{run_id}/reports/{report_type}: Returns the full content of a specific report (such as ACT or REP) for the given execution.
GET /api/executions/{run_id}/reports/download: Streams a ZIP archive containing all report files for the given execution.
GET /api/executions/search: Performs a full-text search across all indexed report content. Requires the q parameter for the search string, and optionally accepts max_results (default: 50) and scan_limit (default: 5000).
GET /api/executions/{run_id}/comments: Returns a paginated list of comments attached to the given execution. Optionally accepts page and size parameters.

Messages (Meldungen)

These endpoints provide access to download or search archived Automation Engine system messages.

GET /api/alerts: Returns a paginated list of archived AE system messages.
GET /api/alerts/download: Streams a CSV file of messages matching the specified filters without size limits.

Message Query Parameters

You can filter your message queries using the following parameters:

Parameter	Type	Default Value	Description
page	integer	0	Zero-based page index.
size	integer	25	Page size.
client	string	None	Filter by AE client number.
user	string	None	Filter by username (substring match).
department	string	None	Filter by department (substring match).
time_frame_from	string	None	Timeframe lower bound in yyyy.MM.dd HH:mm:ss format.
time_frame_to	string	None	Timeframe upper bound in yyyy.MM.dd HH:mm:ss format.
source	string	None	Filter by message source (substring match).
category	string	None	Filter by alert category (substring match).
type	string array	None	Filter by alert type codes (multiple values are OR'd together).
host	string	None	Filter by host name (substring match).
message	string	None	Filter by message text content (substring match).
sort	string	None	Sort expression utilizing the standard execution sort format.

Archives and Status

These administrative endpoints allow you to manage the archive file repository and monitor the progress of the indexing system.

POST /api/archives/upload: Uploads a ucybdbar export ZIP file via multipart/form-data. This endpoint requires the admin role. Overwriting is not permitted; the upload is rejected if any files already exist in the archive folder.
GET /status: Returns the aggregated indexing status across all data categories.
GET /status/archive: Returns the indexing status specifically for Execution (AH) records.
GET /status/report: Returns the indexing status specifically for Report (RH) records.
GET /status/comment: Returns the indexing status specifically for Comment (CO) records.
GET /status/meldung: Returns the indexing status specifically for Message (ML) records.