Skip to main content

​
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

TypeSeverityTrigger
budget_warningwarningSandbox reaches 80% of budget
budget_criticalcriticalSandbox reaches 95% of budget
budget_exceededcriticalSandbox reaches 100% — auto-destroyed
trust_lowwarningTrust score drops below 70
trust_criticalcriticalTrust score drops below 50
sandbox_errorerrorSandbox crashes or enters error state
idle_timeoutinfoSandbox 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

​
enabled
boolean
Enable or disable the rule.
​
threshold
number
Threshold value (0.0 to 1.0 for percentage-based rules).
​
channels
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}
  }
}