Alerts

Alerts notify you of important events — budget thresholds, trust score drops, sandbox errors, and more.

List Alerts

curl https://api.caged.dev/v1/alerts \
  -H "Authorization: Bearer caged_sk_..."

Response 200 OK

[
  {
    "id": "alert-a1b2c3d4",
    "type": "budget_warning",
    "severity": "warning",
    "message": "Sandbox cage-x1y2z3 has used 80% of its $5.00 budget",
    "sandbox_id": "cage-x1y2z3",
    "resolved": false,
    "created_at": "2026-06-08T10:15:00Z"
  }
]

Alert Types

Type	Severity	Trigger
`budget_warning`	warning	Sandbox reaches 80% of budget
`budget_critical`	critical	Sandbox reaches 95% of budget
`budget_exceeded`	critical	Sandbox reaches 100% — auto-destroyed
`trust_low`	warning	Trust score drops below 70
`trust_critical`	critical	Trust score drops below 50
`sandbox_error`	error	Sandbox crashes or enters error state
`idle_timeout`	info	Sandbox auto-paused due to inactivity

Get Alert

curl https://api.caged.dev/v1/alerts/alert-a1b2c3d4 \
  -H "Authorization: Bearer caged_sk_..."

Resolve Alert

curl -X POST https://api.caged.dev/v1/alerts/alert-a1b2c3d4/resolve \
  -H "Authorization: Bearer caged_sk_..."

Alert Rules

Customize which alerts you receive and their thresholds.

List Rules

curl https://api.caged.dev/v1/alerts/rules \
  -H "Authorization: Bearer caged_sk_..."

Response 200 OK

[
  {
    "id": "rule-budget-warn",
    "type": "budget_warning",
    "enabled": true,
    "threshold": 0.8,
    "channels": ["email", "slack"]
  }
]

Update Rule

boolean

Enable or disable the rule.

number

Threshold value (0.0 to 1.0 for percentage-based rules).

string[]

Notification channels: email, slack, discord, webhook.

curl -X PUT https://api.caged.dev/v1/alerts/rules/rule-budget-warn \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"threshold": 0.7, "channels": ["email", "slack"]}'

Notifications

List Notifications

curl https://api.caged.dev/v1/notifications \
  -H "Authorization: Bearer caged_sk_..."

Unread Count

curl https://api.caged.dev/v1/notifications/unread-count \
  -H "Authorization: Bearer caged_sk_..."

{
  "count": 3
}

Mark as Read

curl -X POST https://api.caged.dev/v1/notifications/notif-id/read \
  -H "Authorization: Bearer caged_sk_..."

Mark All Read

curl -X POST https://api.caged.dev/v1/notifications/read-all \
  -H "Authorization: Bearer caged_sk_..."

Notification Config

curl https://api.caged.dev/v1/notifications/config \
  -H "Authorization: Bearer caged_sk_..."

{
  "channels": {
    "email": {"enabled": true, "address": "[email protected]"},
    "slack": {"enabled": true, "webhook_url": "https://hooks.slack.com/..."},
    "discord": {"enabled": false},
    "webhook": {"enabled": false}
  }
}

​Alerts

​List Alerts

​Alert Types

​Get Alert

​Resolve Alert

​Alert Rules

​List Rules

​Update Rule

​Notifications

​List Notifications

​Unread Count

​Mark as Read

​Mark All Read

​Notification Config