Alerts API

The Alerts API provides access to proactive alerts generated by the system when rule health or evaluation patterns require attention. All endpoints are prefixed with /api/v1.

Alert Types

Type	Trigger
`dormant_rule`	A rule has not been evaluated in a configurable period (default 90 days)
`high_deny_rate`	A rule's DENY rate exceeds a threshold (default 50%) over a rolling window
`health_decline`	A rule's health score has dropped significantly since the last measurement
`conflict_detected`	A new or updated rule conflicts with an existing rule in the graph

Alerts are created automatically by the background workers (health score refresh cron job) and by the evaluation pipeline (conflict detection). They can also be triggered by webhook integrations.

Endpoints

GET /api/v1/alerts

List alerts with filtering and pagination.

Query Parameters:

Parameter	Type	Default	Description
`status`	string	--	Filter by status: `active`, `acknowledged`, `resolved`
`alert_type`	string	--	Filter by alert type
`limit`	integer	20	Page size
`offset`	integer	0	Pagination offset

Response:

{
  "total": 12,
  "alerts": [
    {
      "id": "alert-001",
      "type": "high_deny_rate",
      "status": "active",
      "rule_id": "SEC-003",
      "message": "Rule SEC-003 has a 72% DENY rate over the last 30 days",
      "created_at": "2026-04-25T14:30:00Z",
      "metadata": {
        "deny_rate": 0.72,
        "evaluation_count": 45,
        "period_days": 30
      }
    }
  ]
}

GET /api/v1/alerts/{alert_id}

Get a single alert by ID.

POST /api/v1/alerts/{alert_id}/acknowledge

Mark an alert as acknowledged. Acknowledged alerts remain visible but are excluded from active alert counts.

POST /api/v1/alerts/{alert_id}/resolve

Mark an alert as resolved. Optionally include a resolution note.

Request:

{
  "resolution_note": "Rule statement clarified in revision 3; DENY rate expected to drop."
}

Webhooks

Alerts can be forwarded to external systems via webhook. Configure alert webhooks through the gateway policies system. When an alert is created, the system checks for matching webhook policies and delivers the alert payload to the configured URL.