Skip to main content

​
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: 
curl -H "Authorization: Bearer caged_sk_..." https://api.caged.dev/v1/sandboxes
See Authentication for details.

​
Rate Limits

TierRate Limit
Free60 requests/minute
Pro300 requests/minute
Team1000 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: 
{
  "error": "descriptive error message"
}
Status CodeMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid API key
403Forbidden — insufficient permissions or tier limits
404Not found
429Rate limit exceeded
500Internal server error

​
Endpoints Overview

​
Sandboxes

MethodPathDescription
POST/v1/sandboxesCreate a sandbox
GET/v1/sandboxesList sandboxes
GET/v1/sandboxes/:idGet sandbox details
DELETE/v1/sandboxes/:idDestroy a sandbox
POST/v1/sandboxes/:id/pausePause (sleep) a sandbox
POST/v1/sandboxes/:id/resumeResume a paused sandbox

​
Files

MethodPathDescription
GET/v1/sandboxes/:id/filesList directory
GET/v1/sandboxes/:id/files/contentRead file content
PUT/v1/sandboxes/:id/files/contentWrite file content
GET/v1/sandboxes/:id/git/diffGet git diff

​
Terminal

MethodPathDescription
GET/v1/sandboxes/:id/terminalWebSocket terminal session
GET/v1/sandboxes/:id/terminal/sessionsList terminal sessions

​
Ports

MethodPathDescription
GET/v1/sandboxes/:id/portsList detected ports
POST/v1/sandboxes/:id/ports/:port/protectPassword-protect a port

​
Snapshots

MethodPathDescription
GET/v1/sandboxes/:id/snapshotsList snapshots
POST/v1/sandboxes/:id/snapshotsCreate a snapshot
GET/v1/snapshots/:idGet snapshot details
DELETE/v1/snapshots/:idDelete a snapshot
GET/v1/snapshots/:id/downloadGet download URL
POST/v1/snapshots/:id/restoreRestore to a sandbox

​
Billing

MethodPathDescription
GET/v1/billing/subscriptionGet subscription status
POST/v1/billing/checkoutCreate checkout session
POST/v1/billing/portalCreate billing portal link
POST/v1/billing/cancelCancel subscription

​
Alerts

MethodPathDescription
GET/v1/alertsList alerts
GET/v1/alerts/:idGet alert details
POST/v1/alerts/:id/resolveResolve an alert
GET/v1/alerts/rulesList alert rules
PUT/v1/alerts/rules/:idUpdate an alert rule

​
Account

MethodPathDescription
GET/v1/account/keysList API keys
POST/v1/account/keysCreate API key
DELETE/v1/account/keys/:idRevoke API key