Notification rules API
A notification rule decides when ToBeAlert sends a notification, for which alerts, through which method and to whom. Concepts, triggers, conditions and the rule editor are described in Notification rules (Web UI).
All requests need an API key in the Authorization: Key <api-key> header.
Endpoints
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /api/notification/rules | read:notifications | List rules (paging) |
GET | /api/notification/rule/<id> | read:notifications | Get one rule |
POST | /api/notification/rule | write:notifications | Create a rule. At present the key also needs admin (or admin:policies) |
PUT | /api/notification/rule/<id> | write:notifications | Update a rule (only the fields you send) |
DELETE | /api/notification/rule/<id> | write:notifications | Delete a rule |
POST | /api/notification/rule/preview | read:notifications | Build the message a rule would send, without sending it — see Preview |
GET | /api/notification/rules/history | read:notifications | Execution history of all rules |
GET | /api/notification/rule/<id>/history | read:notifications | Execution history of one rule |
DELETE | /api/notification/rules/history | admin:notifications | Delete execution history rows |
Rule fields
| Field | Type | Default | Description |
|---|---|---|---|
name | String | — | Rule name |
description | String | — | Description |
priority | Integer | 0 | Evaluation order, lower first |
status | String | active | active or inactive |
conditions | Object | none | Alert filters, in the same format the rule editor saves ({"operator": "AND", "clauses": [...]}). Empty = every alert |
trigger | String | — | post_receive, status_change, take_action, or recurring for scheduled rules |
recurrent / recurrentConfig | Boolean / Object | false / null | Schedule of a recurring rule |
allDay | Boolean | true | true: the rule may notify at any time. false: only inside the daily window startTime–endTime |
startTime / endTime | ISO 8601 | null | Daily window. Only the hour and minute are used. Required when allDay is false |
method | String | — | Notification method ID |
methodActions | Object or JSON string | — | Recipients and message settings for the method (what the Actions card of the editor saves) |
notificationGroups | Array | [] | Notification group IDs used as recipients when the method actions name none |
Active hours
- A rule created without
allDayis active all day. allDay: falsewithout bothstartTimeandendTimeis rejected with400(startTime and endTime are required when allDay is false), on create and on update.
curl -X POST "https://your-tobealert.com:9000/api/notification/rule" \
-H "Authorization: Key <api-key>" \
-H "Content-Type: application/json" \
-d '{
"name": "j.doe-critical-db",
"description": "Critical alerts on db01 to John Doe",
"trigger": "post_receive",
"conditions": {"operator": "AND", "clauses": [
{"key": "resource", "op": "=", "value": "db01"},
{"key": "severity", "op": "IN", "value": ["critical"]}
]},
"method": "<email-method-id>",
"methodActions": {"to": {"method": "users", "users": ["john.doe@example.com"]}}
}'
Triggers
| Trigger | Fires when |
|---|---|
post_receive | A new alert is received, or an open alert changes severity |
status_change | An alert's status changes. Conditions may also use prev_status |
take_action | A user performs an action on an alert (ack, shelve, close, …). Conditions may also use action and user (login of who performed it) |
recurring | On the schedule in recurrentConfig |
The severity operators more_severe_than / less_severe_than work in rule conditions the same way as in TQL.
Preview
POST /api/notification/rule/preview renders the message a rule would send for one alert, using the same builders as the real send. It does not send anything, does not run code method scripts and does not write history. The rule does not need to be saved: send the settings you want to try.
| Body field | Required | Description |
|---|---|---|
method | Yes | Notification method ID |
methodActions | No | Recipients and message settings (object or JSON string), as in the rule |
alertId | No | Alert to render. Without it, a sample alert is used (web01 / HighCPU, severity major) |
kind | No | open (default) or close. With close the alert is rendered as closed and the rule's close settings (closeConfig) are used |
notificationGroups | No | Group IDs, as in the rule |
Permissions: read:notifications. With alertId, the key also needs read:alerts and must be allowed to see that alert.
curl -X POST "https://your-tobealert.com:9000/api/notification/rule/preview" \
-H "Authorization: Key <api-key>" \
-H "Content-Type: application/json" \
-d '{"method": "<email-method-id>", "kind": "open",
"methodActions": {"to": {"method": "users", "users": ["john.doe@example.com"]},
"subject": {"enabled": true, "hostValue": "[%severity%] %resource% - %event%"}}}'
Response
The shape depends on the method type. Every response has status, kind, sample (true when the sample alert was used), alertId and warnings.
| Method type | Fields |
|---|---|
type: "email", subject, body (HTML), format: "html", from, fromDisplayName, to, cc, bcc (lists of addresses) | |
| Telegram | type: "telegram", body, format (html or markdown), chatId |
| Code | type: "code", body: null. The method script defines the content |
{
"status": "ok",
"type": "email",
"kind": "open",
"sample": true,
"alertId": null,
"subject": "[major] web01 - HighCPU",
"body": "<html>…</html>",
"format": "html",
"from": "alerts@example.com",
"fromDisplayName": "ToBeAlert",
"to": ["john.doe@example.com"],
"cc": [],
"bcc": [],
"warnings": []
}
Configuration problems do not fail the request; they come back in warnings, for example Cannot send email notification: missing recipients, Template not found (<id>), Notification group not found (<id>), CC is enabled but has no address, The severity graph is not included in sent emails, The notification method is disabled: nothing is sent, alsoNotifyOnClose is off: nothing is sent when the alert closes, or Cannot send telegram notification: missing chat ID.
Errors
| Status | When |
|---|---|
400 | Body is not a JSON object, method missing, methodActions not an object, kind not open/close, alertId not a string, notificationGroups not a list of IDs |
403 | alertId sent without read:alerts, or the alert is not visible to the key |
404 | Method or alert not found |