---
title: Alerts
description: "Monitor alerts, manage rules, and handle notifications."
---

# Alerts

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

## List Alerts

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

**Response** `200 OK`

```json
[
  {
    "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

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

## Resolve Alert

```bash
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

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

**Response** `200 OK`

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

### Update Rule

<ParamField body="enabled" type="boolean">
  Enable or disable the rule.
</ParamField>
<ParamField body="threshold" type="number">
  Threshold value (0.0 to 1.0 for percentage-based rules).
</ParamField>
<ParamField body="channels" type="string[]">
  Notification channels: `email`, `slack`, `discord`, `webhook`.
</ParamField>

```bash
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

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

### Unread Count

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

```json
{
  "count": 3
}
```

### Mark as Read

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

### Mark All Read

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

## Notification Config

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

```json
{
  "channels": {
    "email": {"enabled": true, "address": "dev@example.com"},
    "slack": {"enabled": true, "webhook_url": "https://hooks.slack.com/..."},
    "discord": {"enabled": false},
    "webhook": {"enabled": false}
  }
}
```