Alerts API

POST /api/alerts/rules

Create a new alert rule.

Request Body

{
  "name": "High error rate",
  "enabled": true,
  "condition": "error_rate_exceeds",
  "threshold": 0.05,
  "windowMinutes": 60,
  "scope": {
    "agentId": "my-agent",
    "tags": ["production"]
  },
  "notifyChannels": ["https://hooks.slack.com/services/..."]
}

Field	Type	Required	Description
name	string	✅	Rule name (1–200 chars)
enabled	boolean	—	Whether rule is active (default: true)
condition	string	✅	Alert condition (see below)
threshold	number	✅	Threshold value (≥ 0)
windowMinutes	number	✅	Evaluation window in minutes (1–43200)
scope	object	—	Optional scope filter
scope.agentId	string	—	Limit rule to a specific agent
scope.tags	string[]	—	Limit rule to sessions with these tags
notifyChannels	string[]	—	Webhook URLs for notifications

Alert Conditions

Condition	Threshold Unit	Description
error_rate_exceeds	ratio (0–1)	Error events / total events
cost_exceeds	USD	Total cost in window
latency_exceeds	milliseconds	Average tool call latency
event_count_exceeds	count	Total events in window
no_events_for	minutes	No events received for N minutes

Response (201)

{
  "id": "01HXYZ...",
  "name": "High error rate",
  "enabled": true,
  "condition": "error_rate_exceeds",
  "threshold": 0.05,
  "windowMinutes": 60,
  "scope": { "agentId": "my-agent", "tags": ["production"] },
  "notifyChannels": ["https://hooks.slack.com/services/..."],
  "createdAt": "2026-02-08T10:00:00.000Z",
  "updatedAt": "2026-02-08T10:00:00.000Z"
}

curl Example

curl -X POST http://localhost:3400/api/alerts/rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer als_your_key" \
  -d '{
    "name": "High error rate",
    "condition": "error_rate_exceeds",
    "threshold": 0.05,
    "windowMinutes": 60
  }'

---

GET /api/alerts/rules

List all alert rules.

Response (200)

{
  "rules": [
    {
      "id": "01HXYZ...",
      "name": "High error rate",
      "enabled": true,
      "condition": "error_rate_exceeds",
      "threshold": 0.05,
      "windowMinutes": 60,
      "scope": {},
      "notifyChannels": [],
      "createdAt": "2026-02-08T10:00:00.000Z",
      "updatedAt": "2026-02-08T10:00:00.000Z"
    }
  ]
}

---

GET /api/alerts/rules/:id

Get a single alert rule.

Response (200)

Returns a single alert rule object (same shape as in the list).

Errors

Status	Cause
404	Alert rule not found

---

PUT /api/alerts/rules/:id

Update an existing alert rule. Only provided fields are updated.

Request Body

{
  "name": "Updated rule name",
  "enabled": false,
  "threshold": 0.1
}

All fields are optional. Same schema as creation but every field is optional.

Response (200)

Returns the updated alert rule object.

Errors

Status	Cause
400	Validation error
404	Alert rule not found

---

DELETE /api/alerts/rules/:id

Delete an alert rule.

Response (200)

{
  "id": "01HXYZ...",
  "deleted": true
}

Errors

Status	Cause
404	Alert rule not found

---

GET /api/alerts/history

List alert history entries (triggers and resolutions).

Query Parameters

Parameter	Type	Default	Description
ruleId	string	—	Filter by alert rule ID
limit	number	50	Results per page (max: 500)
offset	number	0	Pagination offset

Response (200)

{
  "entries": [
    {
      "id": "01HXYZ...",
      "ruleId": "01HABC...",
      "triggeredAt": "2026-02-08T10:00:00.000Z",
      "resolvedAt": "2026-02-08T10:15:00.000Z",
      "currentValue": 0.08,
      "threshold": 0.05,
      "notified": true
    }
  ],
  "total": 42,
  "hasMore": false
}

curl Example

curl "http://localhost:3400/api/alerts/history?limit=10" \
  -H "Authorization: Bearer als_your_key"