Alerts API
Canonical Alert, Incident, Notification Channel, simulation, and delivery endpoints.
Console endpoints use /api/v1; Management API callers use the same suffix under /management/v1 with a scoped Management Token. Management scopes are alerts:read and alerts:write. Standard API conventions, project restrictions, authorization, pagination, and error envelopes apply.
| Method and path | Purpose |
|---|---|
POST /alerts | Create an Alert. |
GET /alerts?project_id=... | List Alerts. Optional q, trigger_type, and enabled. |
GET /alerts/metadata | Read governed fields, operators, channel types, and policy limits. |
POST /alerts/simulate | Validate and simulate an unsaved Event Alert draft without side effects. |
GET /alerts/{id} | Read an Alert. |
PUT /alerts/{id} | Replace an Alert. |
DELETE /alerts/{id} | Archive and disable an Alert while preserving history. |
POST /alerts/{id}/enable | Enable evaluation. |
POST /alerts/{id}/disable | Disable evaluation. |
POST /alerts/{id}/simulate | Test an Event Alert without side effects. |
GET /notification-channels?project_id=... | List Notification Channels. |
POST /notification-channels | Create a channel. |
GET /notification-channels/{id} | Read a masked channel. |
PUT /notification-channels/{id} | Update a channel. |
POST /notification-channels/{id}/enable | Enable a channel. |
POST /notification-channels/{id}/disable | Disable a channel. |
POST /notification-channels/{id}/test | Queue a test delivery. |
GET /alert-incidents?project_id=... | List Incidents. Optional status, severity, and alert_id. |
GET /alert-incidents/{id} | Read Incident, bounded Occurrences, and deliveries. |
POST /alert-incidents/{id}/acknowledge | Acknowledge an Incident. |
POST /alert-incidents/{id}/resolve | Resolve an Incident. |
GET /alert-deliveries/{id} | Inspect delivery status and last bounded error. |
POST /alert-deliveries/{id}/retry | Requeue an authorized failed or dead_letter delivery. |
GET /api/v1/alerts/metadata is the deterministic Console metadata endpoint for trigger types, operators, channel types, and hard safety limits.
Simulate
curl -sS -X POST "$CORE_URL/api/v1/alerts/$ALERT_ID/simulate" \
-H "Authorization: Bearer $CONSOLE_TOKEN" \
-H "Content-Type: application/json" \
--data '{"event":{"magnitude":6.4,"region":"Aegean"}}'
The response explains each condition and returns safe group and selected-field context. It never changes Incident or delivery state.
For a draft, call POST /api/v1/alerts/simulate with the proposed rule plus sample_event. The Assistant uses this endpoint before it can offer confirmation for Event Alert creation.
Notification policy
cooldown_seconds has a minimum and default of 300 seconds. It controls repeat summaries for one active Incident; the opening notification is queued immediately. Core coalesces pending Incident/channel work and coordinates limits of 10 deliveries per channel per minute and 60 per project per minute. Delivery status is pending, delivering, delivered, failed, or dead_letter.