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

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:

{
  "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

​API Overview

​Base URL

​Authentication

​Rate Limits

​Error Format

​Endpoints Overview

​Sandboxes

​Files

​Terminal

​Ports

​Snapshots

​Billing

​Alerts

​Account