> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> 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 theme={null}
curl https://api.caged.dev/v1/alerts \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
[
  {
    "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 theme={null}
curl https://api.caged.dev/v1/alerts/alert-a1b2c3d4 \
  -H "Authorization: Bearer caged_sk_..."
```

## Resolve Alert

```bash theme={null}
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 theme={null}
curl https://api.caged.dev/v1/alerts/rules \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
[
  {
    "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 theme={null}
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 theme={null}
curl https://api.caged.dev/v1/notifications \
  -H "Authorization: Bearer caged_sk_..."
```

### Unread Count

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

```json theme={null}
{
  "count": 3
}
```

### Mark as Read

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

### Mark All Read

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

## Notification Config

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

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