Incidents

Incidents group related topology events (e.g., a flapping link producing multiple link_state_changed events) into a single correlated entity. All authenticated users can list, view, acknowledge, and resolve incidents.

List Incidents

These existing reads are included in the 1.4.4 OpenAPI reference. Ordinary authenticated roles are supported. Installations from 1.4.4 advertising api_keys.read_only_incidents also allow restricted read-only keys. Access remains installation-wide; acknowledge/resolve and upgrades remain denied.

GET /api/v1/incidents
GET /api/v1/incidents?area_id={areaID}&status={status}&from={from}&to={to}&limit=100&offset=0

List incidents with optional filters. Returns newest created first. Invalid dates are ignored; limits outside 1–1000 or invalid limits fall back to 100. Negative offsets fall back to zero. Unknown status values are passed to the query rather than rejected. Without area_id, the query covers the installation.

Query parameters (all optional):

area_id -- Filter by area UUID
status -- Filter by incident status ("active", "acknowledged", "resolved")
from -- Start time filter, RFC3339 (e.g., "2026-02-16T00:00:00Z")
to -- End time filter, RFC3339 (e.g., "2026-02-17T00:00:00Z")
limit -- Maximum number of incidents to return (default: 100)
offset -- Number of incidents to skip for pagination (default: 0)

Response: 200 OK

{
  "incidents": [
    {
      "id": "uuid",
      "area_id": "uuid",
      "status": "active",
      "severity": "warning",
      "root_cause_type": "device_down",
      "root_cause_id": "10.0.0.1",
      "summary": "Router 10.0.0.1 failure: 3 links down, 2 adjacencies lost",
      "event_count": 5,
      "first_event_at": "2026-02-17T14:30:00Z",
      "last_event_at": "2026-02-17T14:30:02Z",
      "detail": {
        "root_cause_type": "device_down",
        "affected_routers": ["10.0.0.1", "10.0.0.2"]
      },
      "created_at": "2026-02-17T14:30:05Z"
    }
  ],
  "total": 12,
  "limit": 100,
  "offset": 0
}

Notes:

The total field contains the total count of incidents matching the filter (before limit/offset), for pagination.
resolved_at, acknowledged_at, acknowledged_by, and root_cause_id are omitted when unset.
root_cause_type values: device_down, node_failure, asbr_withdrawal, unknown (event-correlated), and area_partition (detector-driven, see below).
area_partition incidents (RFC 2328 §3.7) are raised by the engine's partition detector, not by event correlation: event_count is 0, root_cause_id is absent, and detail carries the split — area_label, consequence ("bridged" | "isolated" | "backbone_partition" | "unknown"), and components, an array of islands each with collector_ids, collector_names, router_ids, and has_backbone_abr. They auto-resolve on positive evidence; detail.resolution_reason records why (e.g. "recorder views overlap again"). Severity follows the consequence: bridged/unknown → warning, isolated/backbone_partition → critical.

Error responses:

500 Internal Server Error -- Failed incident query; malformed query UUIDs can also fail the query.
401 Unauthorized -- Missing or invalid access token

Get Incident

GET /api/v1/incidents/{incidentID}

Get a single incident by ID, including child events when present. From 1.4.4, missing incidents return 404 and database or child-event loading failures return 500. Display-name enrichment remains best effort. Empty child events are omitted; retention may remove historical events. Older versions can return 404 for database failures or silently omit events after a failed read.

Response: 200 OK

{
  "id": "uuid",
  "area_id": "uuid",
  "status": "active",
  "severity": "warning",
  "root_cause_type": "device_down",
  "root_cause_id": "10.0.0.2",
  "summary": "Router 10.0.0.2 failure: 3 links down",
  "event_count": 3,
  "first_event_at": "2026-02-17T14:30:00Z",
  "last_event_at": "2026-02-17T14:35:00Z",
  "detail": {
    "root_cause_type": "device_down",
    "affected_routers": ["10.0.0.2", "10.0.0.3"]
  },
  "created_at": "2026-02-17T14:30:05Z",
  "events": [
    {
      "id": "uuid",
      "event_time": "2026-02-17T14:35:00Z",
      "area_id": "uuid",
      "collector_id": "collector-nyc-dc1-01",
      "event_type": "link_state_changed",
      "entity_type": "link",
      "entity_id": "uuid",
      "router_id": "10.0.0.2",
      "detail": {
        "router_a": "10.0.0.2",
        "router_b": "10.0.0.3",
        "old_state": "up",
        "new_state": "down"
      },
      "incident_id": "uuid"
    }
  ],
  "display_names": {
    "10.0.0.2": "core-rtr-01.ams",
    "10.0.0.3": "edge-rtr-02.ams"
  }
}

Notes:

The events array contains the child topology events belonging to this incident, ordered by event_time descending (newest first).
The display_names field maps router IDs found across all child events to human-readable device names (hostname preferred, dns_name as fallback). Omitted when no names are available.

Error responses:

404 Not Found -- Incident does not exist
401 Unauthorized -- Missing or invalid access token

Acknowledge Incident

PUT /api/v1/incidents/{incidentID}/acknowledge

Acknowledge an open incident. 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 incident object with status: "acknowledged", acknowledged_at and acknowledged_by set)

Error responses:

401 Unauthorized -- Missing or invalid access token
404 Not Found -- Incident does not exist
500 Internal Server Error -- Database error

Resolve Incident

PUT /api/v1/incidents/{incidentID}/resolve

Manually resolve an incident. Sets status to "resolved" and resolved_at to the current time. No request body required. (area_partition incidents also resolve automatically when the partition heals — see List Incidents notes.)

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

Error responses:

401 Unauthorized -- Missing or invalid access token
404 Not Found -- Incident does not exist
500 Internal Server Error -- Database error