Snapshots

Snapshots capture a point-in-time copy of a sandbox's filesystem.

Create Snapshot

curl -X POST https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/snapshots \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "after-setup"}'

Response 201 Created

{
  "id": "snap-e5f6g7h8",
  "sandbox_id": "cage-a1b2c3d4",
  "name": "after-setup",
  "size_bytes": 52428800,
  "status": "completed",
  "created_at": "2026-06-08T10:05:00Z"
}

List Snapshots

curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/snapshots \
  -H "Authorization: Bearer caged_sk_..."

Get Snapshot

curl https://api.caged.dev/v1/snapshots/snap-e5f6g7h8 \
  -H "Authorization: Bearer caged_sk_..."

Delete Snapshot

curl -X DELETE https://api.caged.dev/v1/snapshots/snap-e5f6g7h8 \
  -H "Authorization: Bearer caged_sk_..."

Response 204 No Content

Download Snapshot

Returns a pre-signed URL to download the snapshot as a .tar.gz archive.

curl https://api.caged.dev/v1/snapshots/snap-e5f6g7h8/download \
  -H "Authorization: Bearer caged_sk_..."

Response 200 OK

{
  "url": "https://storage.caged.dev/snapshots/snap-e5f6g7h8.tar.gz?...",
  "expires_at": "2026-06-08T11:05:00Z"
}

Restore Snapshot

Restores a snapshot's contents into a running sandbox.

curl -X POST https://api.caged.dev/v1/snapshots/snap-e5f6g7h8/restore \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"sandbox_id": "cage-a1b2c3d4"}'

Limits