Alerts

Alert instances represent fired alerts from alert rules. All authenticated users can list, view, acknowledge, and resolve alerts.

List Alert Rules (Read)

GET /api/v1/alerts/rules?limit=100&offset=0

List all alert rules. Available to all authenticated users. Returns all rules regardless of enabled state. Supports pagination.

Query parameters:

Response: 200 OK — Paginated envelope

{
  "data": [
    {
      "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": 300,
      "created_by": "uuid",
      "created_at": "2026-02-17T12:00:00Z",
      "updated_at": "2026-02-17T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

List Alert Instances

GET /api/v1/alerts
GET /api/v1/alerts?status=firing&severity=critical&area_id={areaID}&router_id={routerID}&rule_id={ruleID}&from={from}&to={to}&limit=100&offset=0

List alert instances with optional filters. Returns newest first.

Query parameters (all optional):

Response: 200 OK

{
  "alerts": [
    {
      "id": "uuid",
      "rule_id": "uuid",
      "area_id": "uuid",
      "router_id": "10.0.0.2",
      "severity": "critical",
      "status": "firing",
      "summary": "Link between 10.0.0.2 and 10.0.0.3 is down",
      "detail": {
        "router_a": "10.0.0.2",
        "router_b": "10.0.0.3",
        "link_id": "uuid"
      },
      "entity_key": "link:uuid",
      "correlation_key": "link:10.0.0.2|10.0.0.3",
      "fired_at": "2026-02-17T14:30:00Z",
      "resolved_at": null,
      "acknowledged_at": null,
      "acknowledged_by": null,
      "triggering_event_id": "uuid"
    }
  ],
  "total": 5,
  "display_names": {
    "10.0.0.2": "core-rtr-01.ams",
    "10.0.0.3": "edge-rtr-02.ams"
  },
  "scope_labels": {
    "area-uuid": "OSPFv2 · pid 1 · 0.0.0.0"
  }
}

Notes:

Get Alert Instance

GET /api/v1/alerts/{alertID}

Get a single alert instance by ID.

Response: 200 OK (single alert instance object)

Error: 404 Not Found -- Alert does not exist

Acknowledge Alert

PUT /api/v1/alerts/{alertID}/acknowledge

Acknowledge a firing alert. Sets acknowledged_at to the current time and records the acknowledging user's ID in acknowledged_by. No request body required.

Response: 200 OK (updated alert instance object with acknowledged_at and acknowledged_by set)

Error responses:

Resolve Alert

PUT /api/v1/alerts/{alertID}/resolve

Manually resolve an alert. Sets status to "resolved" and resolved_at to the current time. No request body required.

Response: 200 OK (updated alert instance object with status: "resolved" and resolved_at set)

Error responses:

Ignore Alert (Suppress)

PUT /api/v1/alerts/{alertID}/ignore

Suppress future alerts for this alert's rule+entity combination and resolve the current alert. Creates an alert_suppression row from the alert's rule_id and entity_key, then resolves the alert. No request body required.

Response: 200 OK (updated alert instance object with status: "resolved")

Error responses:

Resolve Alert Group

POST /api/v1/alerts/group/resolve

Resolve every firing/acknowledged alert sharing a correlation_key (one physical link's per-address-family / per-area alerts). Publishes one alert.resolved event per resolved member.

Request body: { "correlation_key": "link:10.0.0.2|10.0.0.3" }

Response: 200 OK — { "resolved": <count> }

Errors: 400 Bad Request (missing correlation_key), 500 Internal Server Error

Acknowledge Alert Group

POST /api/v1/alerts/group/acknowledge

Acknowledge every firing alert in the correlation group. Request body as above.

Response: 200 OK — { "acknowledged": <count> }

Errors: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

Ignore Alert Group (Suppress)

POST /api/v1/alerts/group/ignore

Suppress each distinct (rule_id, entity_key) in the correlation group (creating alert_suppression rows), then resolve the whole group. Optional reason.

Request body: { "correlation_key": "link:10.0.0.2|10.0.0.3", "reason": "planned maintenance" }

Response: 200 OK — { "ignored": <count> }

Errors: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

Delete Alert (Engineer/Admin)

DELETE /api/v1/alerts/{alertID}

Permanently delete a single alert instance. Engineer or admin role required. Idempotent: returns 204 even if the alert does not exist.

Response: 204 No Content

Error responses:

Delete All Alerts (Engineer/Admin)

DELETE /api/v1/alerts

Permanently delete every alert instance in the system. Useful for wiping a dev/test environment. Engineer or admin role required. Does not delete alert rules, suppressions, or notification channels.

Response: 204 No Content

Error responses:

List Alert Suppressions

GET /api/v1/alerts/suppressions

List all alert suppressions with the associated rule name. Returns all suppressions (no pagination).

Response: 200 OK

{
  "suppressions": [
    {
      "rule_id": "uuid",
      "rule_name": "Device Down",
      "entity_key": "10.0.0.1",
      "reason": "Known maintenance",
      "created_by": "uuid",
      "created_at": "2026-03-09T12:00:00Z"
    }
  ]
}

Delete Alert Suppression (Admin)

DELETE /api/v1/alerts/suppressions?rule_id={ruleID}&entity_key={entityKey}

Remove a suppression, re-enabling alerting for that rule+entity combination. Engineer or admin.

Query parameters (required):

Response: 204 No Content

Error responses: