Alert Rules (Write)

Engineer or admin CRUD for alert rules. Alert rules define conditions that trigger alert instances when matching topology events occur.

Seeded system alert rules (created by migrations, can be toggled/edited by admins):

• SNMP target auto-disabled -- event_type snmp_target_disabled, fires when a target is auto-disabled after 10 consecutive failures.
• Congestion Warning -- event_type traffic.high_utilization, severity warning, threshold 80% utilization.
• Congestion Critical -- event_type traffic.high_utilization, severity critical, threshold 95% utilization.
• Interface Errors -- event_type interface.errors, severity warning, threshold 1 err/s. Evaluated by the SNMP poller with auto-resolve, cooldown, and deduplication.

Create Alert Rule

POST /api/v1/alerts/rules

Request body:

{
  "name": "Link Down",
  "description": "Alert when a link goes down",
  "severity": "critical",
  "event_type": "link_state_changed",
  "condition": {"state": "down"},
  "scope_type": "area",
  "scope_id": "uuid",
  "enabled": true,
  "cooldown_secs": 600
}

Validation:

• name, event_type, and scope_id are required
• event_type must be a documented event type (see the event-type list under GET /events plus the seeded-rule types snmp_target_disabled / traffic.high_utilization / interface.errors and the service events eigrp_neighbor_down, evpn_mac_move, evpn_pe_lost, l3vpn_vrf_down, mpls_pw_down, mpls_tunnel_down, bgp_moas_observed/bgp_moas_cleared/bgp_own_as_offered, area_stale/area_recovered/area_partition, lsp_purge) or a prefix* glob — anything else is a 400.
• severity defaults to "warning" if omitted (valid values: "critical", "warning", "info" — anything else is a 400)
• scope_type defaults to "area" if omitted (valid values: "area", "protocol_instance", "routing_domain", "network" — anything else is a 400)
• enabled defaults to true if omitted; explicit false creates the rule disabled
• cooldown_secs defaults to 300 (5 minutes) if omitted or <= 0
• condition defaults to {} if omitted
• The same vocabulary checks apply on PUT (per present field)

Response: 201 Created

{
  "id": "uuid",
  "name": "Link Down",
  "description": "Alert when a link goes down",
  "severity": "critical",
  "event_type": "link_state_changed",
  "condition": {"state": "down"},
  "scope_type": "area",
  "scope_id": "uuid",
  "enabled": true,
  "cooldown_secs": 600,
  "created_by": "uuid",
  "created_at": "2026-02-17T12:00:00Z",
  "updated_at": "2026-02-17T12:00:00Z"
}

Error responses:

• 400 Bad Request -- Missing required fields or invalid request body
• 403 Forbidden -- Non-admin user

Get Alert Rule

GET /api/v1/alerts/rules/{ruleID}

Get a single alert rule by ID.

Response: 200 OK (single alert rule object)

Error responses:

• 403 Forbidden -- Non-admin user
• 404 Not Found -- Rule does not exist

Update Alert Rule

PUT /api/v1/alerts/rules/{ruleID}

Partial update of an alert rule. Uses read-merge-write -- only fields present in the request body are updated; other fields are preserved.

Request body (all fields optional):

{
  "name": "Updated Rule Name",
  "description": "Updated description",
  "severity": "warning",
  "event_type": "device_removed",
  "condition": {"new_condition": true},
  "scope_type": "protocol_instance",
  "scope_id": "uuid",
  "enabled": false,
  "cooldown_secs": 120
}

Response: 200 OK (updated alert rule object)

Error responses:

• 400 Bad Request -- Invalid request body
• 403 Forbidden -- Non-admin user
• 404 Not Found -- Rule does not exist

Delete Alert Rule

DELETE /api/v1/alerts/rules/{ruleID}

Delete an alert rule.

Response: 204 No Content

Error responses:

• 403 Forbidden -- Non-admin user
• 500 Internal Server Error -- Database error

Toggle Alert Rule

PUT /api/v1/alerts/rules/{ruleID}/toggle

Flip the enabled flag on an alert rule. If the rule is currently enabled, it becomes disabled, and vice versa.

Response: 200 OK (updated alert rule object with toggled enabled field)

Error responses:

• 403 Forbidden -- Non-admin user
• 404 Not Found -- Rule does not exist

List Rule Notification Channels

GET /api/v1/alerts/rules/{ruleID}/channels

Returns notification channels linked to this alert rule, including the notify_on setting for each.

Response: 200 OK

[
  {
    "channel_id": "uuid",
    "channel_name": "Slack Ops",
    "channel_type": "slack",
    "notify_on": "both",
    "enabled": true
  }
]

Set Rule Notification Channels

PUT /api/v1/alerts/rules/{ruleID}/channels

Replaces all notification channel links for an alert rule. Existing links are removed and replaced with the provided list.

Request body:

[
  { "channel_id": "uuid-1", "notify_on": "both" },
  { "channel_id": "uuid-2", "notify_on": "firing" }
]

• notify_on must be "firing", "resolved", or "both".

Response: 200 OK (updated list of linked channels)

Error responses:

• 400 Bad Request -- Invalid notify_on value or missing channel_id
• 403 Forbidden -- Non-admin user