The Caged API is a REST API served at https://api.caged.dev. All requests and responses use JSON.
https://api.caged.dev/v1
All API requests (except signup/login and pricing) require a Bearer token:
curl -H "Authorization: Bearer caged_sk_..." https://api.caged.dev/v1/sandboxes
See Authentication for details.
| 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
All errors return a consistent JSON structure:
{
"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 |
| 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 |
| 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 |
| Method |
Path |
Description |
GET |
/v1/sandboxes/:id/terminal |
WebSocket terminal session |
GET |
/v1/sandboxes/:id/terminal/sessions |
List terminal sessions |
| Method |
Path |
Description |
GET |
/v1/sandboxes/:id/ports |
List detected ports |
POST |
/v1/sandboxes/:id/ports/:port/protect |
Password-protect a port |
| 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 |
| 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 |
| 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 |
| 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 |
