> ## 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.

# API Overview

> REST API reference for the Caged platform.

# API Overview

The Caged API is a REST API served at `https://api.caged.dev`. All requests and responses use JSON.

## Base URL

```
https://api.caged.dev/v1
```

## Authentication

All API requests (except signup/login and pricing) require a Bearer token:

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

See [Authentication](/api-reference/authentication) for details.

## Rate Limits

| Tier | Rate Limit           |
| ---- | -------------------- |
| Free | 60 requests/minute   |
| Pro  | 300 requests/minute  |
| Team | 1000 requests/minute |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1700000000
```

## Error Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": "descriptive error message"
}
```

| Status Code | Meaning                                             |
| ----------- | --------------------------------------------------- |
| 400         | Bad request — invalid parameters                    |
| 401         | Unauthorized — missing or invalid API key           |
| 403         | Forbidden — insufficient permissions or tier limits |
| 404         | Not found                                           |
| 429         | Rate limit exceeded                                 |
| 500         | Internal server error                               |

## Endpoints Overview

### Sandboxes

| Method   | Path                       | Description             |
| -------- | -------------------------- | ----------------------- |
| `POST`   | `/v1/sandboxes`            | Create a sandbox        |
| `GET`    | `/v1/sandboxes`            | List sandboxes          |
| `GET`    | `/v1/sandboxes/:id`        | Get sandbox details     |
| `DELETE` | `/v1/sandboxes/:id`        | Destroy a sandbox       |
| `POST`   | `/v1/sandboxes/:id/pause`  | Pause (sleep) a sandbox |
| `POST`   | `/v1/sandboxes/:id/resume` | Resume a paused sandbox |

### Files

| Method | Path                              | Description        |
| ------ | --------------------------------- | ------------------ |
| `GET`  | `/v1/sandboxes/:id/files`         | List directory     |
| `GET`  | `/v1/sandboxes/:id/files/content` | Read file content  |
| `PUT`  | `/v1/sandboxes/:id/files/content` | Write file content |
| `GET`  | `/v1/sandboxes/:id/git/diff`      | Get git diff       |

### Terminal

| Method | Path                                  | Description                |
| ------ | ------------------------------------- | -------------------------- |
| `GET`  | `/v1/sandboxes/:id/terminal`          | WebSocket terminal session |
| `GET`  | `/v1/sandboxes/:id/terminal/sessions` | List terminal sessions     |

### Ports

| Method | Path                                    | Description             |
| ------ | --------------------------------------- | ----------------------- |
| `GET`  | `/v1/sandboxes/:id/ports`               | List detected ports     |
| `POST` | `/v1/sandboxes/:id/ports/:port/protect` | Password-protect a port |

### Snapshots

| Method   | Path                          | Description          |
| -------- | ----------------------------- | -------------------- |
| `GET`    | `/v1/sandboxes/:id/snapshots` | List snapshots       |
| `POST`   | `/v1/sandboxes/:id/snapshots` | Create a snapshot    |
| `GET`    | `/v1/snapshots/:id`           | Get snapshot details |
| `DELETE` | `/v1/snapshots/:id`           | Delete a snapshot    |
| `GET`    | `/v1/snapshots/:id/download`  | Get download URL     |
| `POST`   | `/v1/snapshots/:id/restore`   | Restore to a sandbox |

### Billing

| Method | Path                       | Description                |
| ------ | -------------------------- | -------------------------- |
| `GET`  | `/v1/billing/subscription` | Get subscription status    |
| `POST` | `/v1/billing/checkout`     | Create checkout session    |
| `POST` | `/v1/billing/portal`       | Create billing portal link |
| `POST` | `/v1/billing/cancel`       | Cancel subscription        |

### Alerts

| Method | Path                     | Description          |
| ------ | ------------------------ | -------------------- |
| `GET`  | `/v1/alerts`             | List alerts          |
| `GET`  | `/v1/alerts/:id`         | Get alert details    |
| `POST` | `/v1/alerts/:id/resolve` | Resolve an alert     |
| `GET`  | `/v1/alerts/rules`       | List alert rules     |
| `PUT`  | `/v1/alerts/rules/:id`   | Update an alert rule |

### Account

| Method   | Path                   | Description                   |
| -------- | ---------------------- | ----------------------------- |
| `GET`    | `/v1/account`          | Get the authenticated account |
| `GET`    | `/v1/account/keys`     | List API keys                 |
| `POST`   | `/v1/account/keys`     | Create API key                |
| `DELETE` | `/v1/account/keys/:id` | Revoke API key                |