Rest API Overview

REST API Overview

CIB ins7ght exposes a REST API for accessing process analytics, statistics, incidents, and configuration data.

Base URL: http://localhost:8899 (configurable via server.port)

License and access: Most analytics, process, and incident endpoints require a valid enterprise license and return HTTP 403 when the license is missing or invalid. Optional user authentication is controlled with ins7ght.authentication.enabled.

API Categories

1. Overview Statistics API

Base Path: /overview

Aggregated metrics and time-series data. All routes use POST with a JSON body (OverviewRequest: processKey, version, startDate, endDate).

Endpoints:

• POST /overview/graph/started-instances — Time series of started instances
• POST /overview/graph/finalized-instances — Time series of finalized instances
• POST /overview/graph/successful-instances — Time series of successful instances
• POST /overview/graph/canceled-instances — Time series of canceled instances
• POST /overview/graph/incident-instances — Time series of instances with incidents
• POST /overview/started-instances — Count of started instances
• POST /overview/finalized-instances — Count of finalized instances
• POST /overview/successful-instances — Count of successful instances
• POST /overview/avg-process-duration — Average process duration (ms)
• POST /overview/canceled-instances-internally-terminated — Canceled (internal)
• POST /overview/canceled-instances-externally-terminated — Canceled (external)
• POST /overview/error-start-event-instances — Error start event instances
• POST /overview/incident-instances — Instances with incidents (count)
• POST /overview/completed-user-tasks-percentage — Completed user tasks (%)
• POST /overview/avg-user-task-duration — Average user task duration (ms)
• POST /overview/top-user-tasks — Top user tasks

View Details →

2. Process Analysis API

Base Path: /process-analysis

Activity-level metrics, bottleneck detection, and outlier identification (GET with query parameters; states is required where noted).

Endpoints:

• GET /process-analysis/activity — Activity-level statistics
• GET /process-analysis/activity-duration — Duration between two activities
• GET /process-analysis/outliers — Outlier process instances
• GET /process-analysis/duration — Duration distribution
• GET /process-analysis/thresholds — Calculated outlier thresholds
• GET /process-analysis/version-duration — Version comparison statistics

View Details →

3. Process API

Base Path: /process

Process definitions, versions, allowed states, and BPMN diagrams.

Endpoints:

• GET /process — List process definitions (optional startDate, endDate)
• GET /process/{processKey}/version — Versions for a process (returns process metadata objects)
• GET /process/states — Distinct process states for a key/version and optional range
• GET /process/bpmn — BPMN XML (processKey, version)

View Details →

4. Info API

Base Path: /info

Application metadata and configuration exposed to the frontend.

Endpoints:

• GET /info — Application version (plain text)
• GET /info/properties — Configuration (JSON)

View Details →

5. Polling Info API

Base Path: /poll-info

Polling status for synchronization with the engine (JSON array).

Endpoints:

• GET /poll-info — Polling status and timestamps

View Details →

6. Incidents API

Base Path: /incidents

Incident heatmaps, graphs, tables, and totals.

Endpoints:

• GET /incidents/heatmap
• GET /incidents/incident-version-graph
• GET /incidents/incidents-table
• GET /incidents/incidents-graph
• GET /incidents/total-counts

View Details →

7. Authentication and license

Endpoints:

• GET /auth — Current user (when authentication is enabled)
• GET /system/license/status — License information JSON

View Details →

7. Authentication and license

Endpoints:

• GET /auth — Current user (when authentication is enabled)
• GET /system/license/status — License information JSON

View Details →

7. Authentication and license

Endpoints:

• GET /auth — Current user (when authentication is enabled)
• GET /system/license/status — License information JSON

View Details →

Quick Start

Get Application Version

curl -X GET "http://localhost:8899/info"

Get All Processes

curl -X GET "http://localhost:8899/process"

Get Overview Statistics (POST + JSON body)

curl -X POST "http://localhost:8899/overview/started-instances" \
  -H "Content-Type: application/json" \
  -d "{\"processKey\":[\"invoice-process\"],\"version\":\"1\"}"

Get Activity Analysis

curl -G "http://localhost:8899/process-analysis/activity" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1" \
  --data-urlencode "states=COMPLETED"

Check Polling Status

curl -X GET "http://localhost:8899/poll-info"

Common Parameters

Overview (POST body, JSON)

Process analysis (GET query)

Response Formats

JSON

Most endpoints return JSON data.

{
  "field": "value",
  "numericField": 123,
  "arrayField": [1, 2, 3]
}

Plain Text

The /info endpoint returns plain text.

0.0.2-SNAPSHOT 2026-01-29-1200

Binary (XML)

The /process/bpmn endpoint returns BPMN XML as binary data.

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions ...>
  ...
</bpmn:definitions>

Data Types

Timestamps

• Format: ISO 8601 with timezone (e.g., 2026-01-29T10:30:00Z)
• Unix Epoch: Long integers representing milliseconds since 1970-01-01 (e.g., 1704067200000)

Durations

• Format: Long integers representing milliseconds
• Example: 3600000 (1 hour)

Process Identifiers

• Process Key: String identifier for a process definition (e.g., invoice-process)
• Version: String representing version number (e.g., 1, 2)
• Process ID: Full process definition ID from CIB seven (e.g., invoice-process:1:abc123)

Error Handling

Example response (HTTP 200)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "..."
}

Example response (HTTP 500)

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "timestamp": "2026-01-29T10:30:00.000+00:00",
  "status": 500,
  "error": "Internal Server Error",
  "message": "No Process Key provided",
  "path": "/overview/started-instances"
}

Common scenarios:

• Missing or invalid parameters → 500 with descriptive message (varies by endpoint)
• Invalid process key/version → Empty array, null, or empty list depending on endpoint
• Database issues → 500
• Invalid or missing license on enterprise routes → 403

License denied (enterprise routes)

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "timestamp": "2026-05-06T12:00:00.000+00:00",
  "status": 403,
  "error": "Forbidden",
  "message": "License is invalid. Enterprise features are not available.",
  "path": "/process"
}

CORS

CIB ins7ght does not configure CORS headers by default. If cross-origin access is required, configure CORS at the reverse proxy level.

Authentication

There is no separate API-key layer in the application. Optional user authentication is configured with ins7ght.authentication.enabled and the CIB seven webclient stack. Enterprise analytics require a valid license file, independent of user login.

Network-level controls and reverse-proxy authentication remain recommended for production. See Security Instructions.

Rate Limiting

No rate limiting is implemented in the application. Consider rate limiting at the reverse proxy or infrastructure level if needed.

API Versioning

The REST API is not versioned in the URL. Breaking changes are communicated via release notes.

Testing the API

Using cURL

# Overview (POST)
curl -X POST "http://localhost:8899/overview/finalized-instances" \
  -H "Content-Type: application/json" \
  -d "{\"processKey\":[\"invoice-process\"],\"version\":\"1\"}"

# Pretty print JSON response
curl -X GET "http://localhost:8899/poll-info" | jq .

Using Browser

These GET endpoints can be opened directly:

http://localhost:8899/process
http://localhost:8899/poll-info
http://localhost:8899/info/properties

API Documentation by Category

1. Overview Statistics API — Aggregated metrics and time-series (POST)
2. Process Analysis API — Activity analysis and bottlenecks

• See Configuration Guide for application.yaml / cib-ins7ght.yaml.

5. Polling Info API — Polling status (/poll-info)
6. Incidents API — Incident analytics

Need Help?

• Use the detail pages above for parameters and examples.
• See Configuration Guide for application.yaml / cib-ins7ght.yaml.
• See Troubleshooting for common issues.