Alerts

Create and manage alert rules for agent behavior monitoring.

Alerts

Alert rules monitor agent telemetry and notify you when thresholds are exceeded. Alerts can trigger on error rates, latency, denied request rates, or volume drops.

The Alert Object

json

{
  "id": "01916d00-aaaa-bbbb-cccc-dddddddddddd",
  "agent_id": "01916a3e-7b2c-...",
  "condition_type": "error_rate",
  "threshold": 0.05,
  "window_minutes": 15,
  "channel": "email",
  "channel_target": "oncall@company.com",
  "cooldown_minutes": 60,
  "notification_count": 3,
  "is_enabled": true,
  "last_triggered_at": "2026-04-12T03:15:00Z",
  "created_at": "2026-04-10T14:30:00Z"
}

Field	Type	Description
`condition_type`	string	`error_rate`, `latency_p99`, `denied_rate`, or `volume_drop`.
`threshold`	number	Threshold value (must be > 0).
`window_minutes`	integer	Evaluation window (default 15).
`channel`	string	`email` or `webhook`.
`channel_target`	string	Email address or webhook URL.
`cooldown_minutes`	integer	Minimum time between notifications (default 60).

Create an Alert

POST /v1/alerts

Auth: JWT (member+)

Parameter	Type	Required	Description
`agent_id`	UUID	Yes	Agent to monitor.
`condition_type`	string	Yes	One of `error_rate`, `latency_p99`, `denied_rate`, `volume_drop`.
`threshold`	number	Yes	Threshold value (> 0).
`window_minutes`	integer	No	Evaluation window in minutes (default 15).
`channel`	string	Yes	`email` or `webhook`.
`channel_target`	string	Yes	Notification destination.
`cooldown_minutes`	integer	No	Cooldown between alerts (default 60).

bash

curl -X POST https://api.checkrd.io/v1/alerts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "01916a3e-7b2c-...",
    "condition_type": "error_rate",
    "threshold": 0.05,
    "channel": "email",
    "channel_target": "oncall@company.com"
  }'

Response 200 OK -- Returns the alert object.

List Alerts

GET /v1/alerts

Auth: JWT (viewer+)

Supports limit and cursor pagination. Returns alerts with their associated agent names.

Update an Alert

PUT /v1/alerts/:alert_id

Auth: JWT (member+)

All fields are optional. Only the fields you pass are updated; omitted fields keep their current values. Returns the updated alert object.

Delete an Alert

DELETE /v1/alerts/:alert_id

Auth: JWT (admin+)

Returns { "success": true }.

Toggle an Alert

POST /v1/alerts/:alert_id/toggle

Auth: JWT (member+)

Parameter	Type	Required	Description
`is_enabled`	boolean	Yes	Enable or disable the alert.

bash

curl -X POST https://api.checkrd.io/v1/alerts/01916d00-.../toggle \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

Response 200 OK: returns the updated alert object.

Mute an Alert

POST /v1/alerts/:alert_id/mute

Auth: JWT (member+)

Suppresses notifications for a fixed window. The alert keeps evaluating but won't send email or webhook events until the mute expires.

Parameter	Type	Required	Description
`until`	RFC 3339	Yes	When the mute expires.
`reason`	string	No	Free-text note for the audit log.

Response 200 OK: returns the updated alert with muted_until populated.

Unmute an Alert

POST /v1/alerts/:alert_id/unmute

Auth: JWT (member+)

Clears the muted_until field immediately. Notifications resume on the next state transition.

Response 200 OK: returns the updated alert.

List Alert History

GET /v1/alerts/:alert_id/history

Auth: JWT (viewer+)

Returns the state-transition history for one alert: each firing / resolved transition with timestamps and the metric value that caused the change.

Parameter	Type	Required	Description
`limit`	integer	No	Results per page (default 50, max 200).
`cursor`	string	No	Opaque pagination cursor.

Response 200 OK: paginated list of state transitions.

List Sent Notifications

GET /v1/alerts/:alert_id/notifications

Auth: JWT (viewer+)

Returns the notifications dispatched for this alert: each email or webhook delivery attempt, status (delivered / failed / retrying), and the recipient.

Parameter	Type	Required	Description
`limit`	integer	No	Results per page (default 50, max 200).
`cursor`	string	No	Opaque pagination cursor.

Response 200 OK: paginated list of dispatch records.

Dashboard Control