Integrations API
An integration connects ToBeAlert to an external monitoring system (today Checkmk) with a stored credential and is linked to one alert source. For an alert with that source, the API returns the graphs the external system has for the alert. Concepts and the Web UI are described in Integrations (Web UI).
All requests need an API key in the Authorization: Key <api-key> header.
Endpoints
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /api/integrations | read:integrations | List integrations (paging and q search like other lists). The response also carries types, the available integration types |
POST | /api/integration | write:integrations | Create an integration |
GET | /api/integration/<id> | read:integrations | Get one integration |
PUT | /api/integration/<id> | write:integrations | Update an integration (only the fields you send) |
DELETE | /api/integration/<id> | write:integrations | Delete an integration and its stored secret |
POST | /api/integration/<id>/test | write:integrations | Test the saved integration (its config and stored secret) |
POST | /api/integrations/test | write:integrations | Test a configuration without saving it |
GET | /api/alert/<alert_id>/integration | read:integrations and the alert must be visible to the caller | Graphs of the external system for the alert, also for an alert that only exists in the history — see Alert graphs |
admin:integrations includes read and write. There is no delete:integrations: delete needs write:integrations.
Integration fields
| Field | Type | Description |
|---|---|---|
id | String | Generated UUID |
name | String | Required. Shown as the title of the Integration section in the alert details |
type | String | Required. checkmk. Cannot be changed with PUT (400 the type of an integration cannot be changed) |
sourceId | String | Required. Name of an existing alert source. One integration per source |
enabled | Boolean | Default true. A disabled integration answers 404 on the alert graphs endpoint |
config | Object | Type-specific configuration, validated and completed on save. Never contains the secret |
secret | String | Write-only. The credential of the external system (Checkmk automation secret). Stored encrypted with the server secret key |
secretSet | Boolean | Read-only. A secret is stored |
secretStale | Boolean | Read-only. A secret is stored but cannot be decrypted (the server secret key changed). Send secret again |
createTime, updateTime, createdBy | — | Read-only |
Checkmk config
| Key | Default | Description |
|---|---|---|
baseUrl | — | Required. http:// or https://, host and port, without the API path. A trailing /<site> is stripped so it is not duplicated. ToBeAlert calls <baseUrl>/<site>/check_mk/api/1.0 |
site | — | Required. Checkmk site name (letters, digits, -, _) |
username | — | Required. Automation user. Requests use Authorization: Bearer <username> <secret> |
tlsVerify | true | Verify the TLS certificate |
caCert | — | Optional PEM certificate of the CA to trust |
fieldMapping | {"host": "attributes.checkmk_host", "service": "attributes.checkmk_service", "site": "attributes.checkmk_site"} | Paths inside the serialized alert that hold the Checkmk host, service and site. A path that exists with an empty service means a host alert |
fallback | {"host": "resource", "service": "event"} | Paths read only when the mapped path is absent from the alert |
Keys you omit take the defaults; the saved config is returned complete.
Secret handling
POST /api/integrationwithoutsecretcreates the integration withsecretSet: false; tests and graphs fail until a secret is stored.PUT: a newsecretreplaces the stored one;secretabsent, empty or"******"keeps it;"clearSecret": trueremoves it.- Responses never include the secret. Audit trail events
integration-created,integration-updated,integration-deletedandintegration-testedrecord the user, the integration and the result, never the secret.
curl -X POST "https://your-tobealert.com:9000/api/integration" \
-H "Authorization: Key <api-key>" \
-H "Content-Type: application/json" \
-d '{
"name": "j.doe-checkmk",
"type": "checkmk",
"sourceId": "checkmk",
"enabled": true,
"config": {"baseUrl": "https://your-checkmk.example.com", "site": "mysite", "username": "tobealert"},
"secret": "<automation-secret>"
}'
Response 201:
{
"status": "ok",
"id": "d8bd0de3-964e-4acb-8131-40b81c766ca7",
"integration": {
"id": "d8bd0de3-964e-4acb-8131-40b81c766ca7",
"name": "j.doe-checkmk",
"type": "checkmk",
"sourceId": "checkmk",
"enabled": true,
"config": {
"baseUrl": "https://your-checkmk.example.com",
"site": "mysite",
"username": "tobealert",
"tlsVerify": true,
"fieldMapping": {"host": "attributes.checkmk_host", "service": "attributes.checkmk_service", "site": "attributes.checkmk_site"},
"fallback": {"host": "resource", "service": "event"}
},
"secretSet": true,
"secretStale": false,
"createTime": "2026-10-24T16:20:24.821Z",
"updateTime": null,
"createdBy": "j.doe"
}
}
Errors on create and update
| Status | Message | Cause |
|---|---|---|
400 | unknown integration type "…" | type is not registered |
400 | config.baseUrl is required, config.site must contain only …, … | Invalid Checkmk configuration |
400 | alert source '…' not found | sourceId does not exist. Create it first (POST /api/alert_source) |
409 | alert source '…' is already linked to integration '…' | One integration per source |
404 | integration not found | Unknown id |
Test a connection
POST /api/integration/<id>/test uses the saved configuration and secret. POST /api/integrations/test takes the form to test:
{"type": "checkmk", "config": {"baseUrl": "https://your-checkmk.example.com", "site": "mysite", "username": "tobealert"}, "secret": "<automation-secret>", "id": "<existing-id>"}
secret may be omitted (or "******") when id names an integration with a stored secret. Success:
{"status": "ok", "version": "2.2.0p1.cee", "edition": "cee", "site": "mysite", "warnings": []}
warnings contains Checkmk 2.2 or newer is required for graphs when the site is older than 2.2. A failure answers 502:
{"status": "error", "code": "upstream", "message": "Checkmk rejected the credentials (401): check the automation user and secret"}
Alert graphs
GET /api/alert/<alert_id>/integration?window=4h
| Parameter | Values | Default |
|---|---|---|
window | 1h, 4h, 24h, 7d | 4h |
The time range is createTime − window to min(now, createTime + window): open alerts are shown up to now, old alerts centred on the alert. Results are cached for 60 seconds per integration, host, service and window (cached: true on a cache hit).
The alert is looked up in the live alerts first. If it is no longer there (housekeeping deleted it) but it has entries in the alert history, the target is rebuilt from its last history entry and the graphs are centred on the creation time of the alert; source tells which case applies. The Web UI uses this from Alerts → History (point-in-time details drawer and Summary tab of the per-alert timeline), where it shows Graph around the alert time, from history.
{
"status": "ok",
"integration": {"id": "d8bd0de3-964e-4acb-8131-40b81c766ca7", "name": "j.doe-checkmk", "type": "checkmk"},
"target": {
"host": "john-doe-srv01",
"service": "CPU load",
"site": "mysite",
"url": "https://your-checkmk.example.com/mysite/check_mk/index.py?start_url=view.py%3Fview_name%3Dservice%26host%3Djohn-doe-srv01%26service%3DCPU%2Bload"
},
"timeRange": {"start": "2026-10-24T12:20:25.035Z", "end": "2026-10-24T16:20:25.103Z", "window": "4h"},
"alertTime": "2026-10-24T16:20:25.035Z",
"source": "alert",
"charts": [
{
"id": "load1",
"title": "CPU load average of last minute",
"series": [
{"name": "CPU load average of last minute", "color": "#00e060", "lineType": "area", "points": [[1761308425000, 1.5], [1761308485000, null]]}
]
}
],
"warnings": [],
"cached": false
}
| Field | Description |
|---|---|
source | alert when the alert is in the live alerts, history when it was resolved from the alert history because it no longer exists |
alertTime | Creation time of the alert; the time range and the Alert mark are built around it |
target | Host, service (null for a host alert), site and the link to the object in the external system |
charts[] | One chart per metric: id (metric id), title, series[] with name, color, lineType (line, area, …) and points as [timestamp_ms, value]; value is null where the external system has no data. When the metric name was translated from the performance data name, perfName holds the original name |
warnings[] | Human-readable notes: fallback used for the host or service, host or service not found, no metrics, more than 16 metrics (only the first 16 are returned), metrics that could not be graphed, Checkmk older than 2.2 |
Errors
| Status | Body | Cause |
|---|---|---|
400 | window must be one of: 1h, 4h, 24h, 7d | Invalid window |
403 | You do not have permission to view this alert | The alert is outside the caller's views |
404 | alert not found | The alert is neither in the live alerts nor in the alert history. A caller restricted by views also gets 404 for an alert that is no longer in the live alerts, as with GET /api/alert/<alert_id>/history |
404 | no integration: the alert has no source / no integration for source '…' | The alert has no sourceId, or no enabled integration is linked to it. The Web UI hides the section |
422 | Could not resolve the host from the alert (with errors listing the paths read) | The mapped host path and its fallback are empty |
502 | {"status": "error", "code": "upstream", "message": "…"} | Checkmk rejected the credentials (401/403), could not be reached, timed out, or answered an unexpected status |
Unknown host or service, services without metrics and Checkmk versions older than 2.2 are not errors: the response is 200 with charts: [] and the reason in warnings.
Visibility follows the same rules as the alert itself: a live alert must be inside the caller's views; an alert that only exists in the history is served to administrators and to callers whose views cover every alert, as with GET /api/alert/<alert_id>/history.
Related
- Checkmk notification script — how Checkmk alerts get their
sourceIdandattributes.checkmk_* - Sending alerts — alert fields, including
sourceId - API keys — Permission categories