Alerts API

Normalized, filterable feed of event-type items across layers — query and facet endpoints.

The alerts API is a single, normalized event feed unified across every layer that produces discrete events (incidents, advisories, anomalies, escalations). Each item carries a stable shape so the same query and the same UI work regardless of which underlying layer the event came from.

Routes

Method	Path	Purpose
`GET`	`/alerts`	Query alerts with full filter set.
`GET`	`/alerts/facets`	Facet counts (types, sources, severities, layers) for the current filter.

Filters

All filters compose. Omit to match everything.

Param	Type	Notes
`types`	csv	Alert types (`incident`, `advisory`, `anomaly`, `escalation`, …).
`sources`	csv	Source feed ids that produced the alert.
`severity`	csv	One or more of `low`, `medium`, `high`, `critical`.
`layers`	csv	Restrict to alerts whose origin layer matches.
`q`	string	Free-text query against title/description.
`since`	RFC3339 or duration	e.g. `2026-05-01T00:00:00Z`, `24h`, `7d`.
`until`	RFC3339 or duration	Inclusive upper bound.
`bbox`	`minLon,minLat,maxLon,maxLat`	Spatial filter (R-tree).
`aoi`	string	Restrict to the named AOI (see operator control plane).
`limit`	int	Default `200`, max `2000`.
`offset`	int	Pagination cursor.

Response shape

{
  "total": 4831,
  "alerts": [
    {
      "id": "alr_…",
      "type": "anomaly",
      "severity": "high",
      "layer": "ais",
      "title": "Anchor-drag pattern near subsea cable",
      "ts": "2026-05-27T18:12:04Z",
      "geometry": { "type": "Point", "coordinates": [55.21, 26.07] },
      "props": { /* layer-specific */ }
    }
  ]
}

GET /alerts/facets returns the same filter dimensions broken down into counts for the current filter set — useful for driving filter UIs:

{
  "types":      { "incident": 1240, "anomaly": 380, "advisory": 91 },
  "severities": { "low": 700, "medium": 800, "high": 211 },
  "layers":     { "ais": 480, "adsb": 220, "natural": 91 },
  "sources":    { /* … */ }
}

Mapping to the UI

The Farsight /farsight/alerts view consumes these two endpoints directly — the filter sidebar reads facets, the result list reads alerts, and the map spatial bound rides the bbox parameter.

Status

Live on the deployed system. Push streaming of new alerts is planned but not yet deployed — poll /alerts?since=… until then.