Skip to main content
Version: 1.4 (Current)

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​

MethodPathPermissionDescription
GET/api/integrationsread:integrationsList integrations (paging and q search like other lists). The response also carries types, the available integration types
POST/api/integrationwrite:integrationsCreate an integration
GET/api/integration/<id>read:integrationsGet one integration
PUT/api/integration/<id>write:integrationsUpdate an integration (only the fields you send)
DELETE/api/integration/<id>write:integrationsDelete an integration and its stored secret
POST/api/integration/<id>/testwrite:integrationsTest the saved integration (its config and stored secret)
POST/api/integrations/testwrite:integrationsTest a configuration without saving it
GET/api/alert/<alert_id>/integrationread:integrations and the alert must be visible to the callerGraphs 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​

FieldTypeDescription
idStringGenerated UUID
nameStringRequired. Shown as the title of the Integration section in the alert details
typeStringRequired. checkmk. Cannot be changed with PUT (400 the type of an integration cannot be changed)
sourceIdStringRequired. Name of an existing alert source. One integration per source
enabledBooleanDefault true. A disabled integration answers 404 on the alert graphs endpoint
configObjectType-specific configuration, validated and completed on save. Never contains the secret
secretStringWrite-only. The credential of the external system (Checkmk automation secret). Stored encrypted with the server secret key
secretSetBooleanRead-only. A secret is stored
secretStaleBooleanRead-only. A secret is stored but cannot be decrypted (the server secret key changed). Send secret again
createTime, updateTime, createdBy—Read-only

Checkmk config​

KeyDefaultDescription
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>
tlsVerifytrueVerify 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/integration without secret creates the integration with secretSet: false; tests and graphs fail until a secret is stored.
  • PUT: a new secret replaces the stored one; secret absent, empty or "******" keeps it; "clearSecret": true removes it.
  • Responses never include the secret. Audit trail events integration-created, integration-updated, integration-deleted and integration-tested record 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​

StatusMessageCause
400unknown integration type "…"type is not registered
400config.baseUrl is required, config.site must contain only …, …Invalid Checkmk configuration
400alert source '…' not foundsourceId does not exist. Create it first (POST /api/alert_source)
409alert source '…' is already linked to integration '…'One integration per source
404integration not foundUnknown 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

ParameterValuesDefault
window1h, 4h, 24h, 7d4h

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
}
FieldDescription
sourcealert when the alert is in the live alerts, history when it was resolved from the alert history because it no longer exists
alertTimeCreation time of the alert; the time range and the Alert mark are built around it
targetHost, 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​

StatusBodyCause
400window must be one of: 1h, 4h, 24h, 7dInvalid window
403You do not have permission to view this alertThe alert is outside the caller's views
404alert not foundThe 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
404no 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
422Could 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.