---
title: API Overview
description: "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
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
{
  "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 |