> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Create, restore, fork, and download sandbox snapshots.

# Snapshots

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

## Create Snapshot

<ParamField body="name" type="string" required>
  Descriptive name for the snapshot.
</ParamField>

```bash theme={null}
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`

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

## List Snapshots

```bash theme={null}
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/snapshots \
  -H "Authorization: Bearer caged_sk_..."
```

## Get Snapshot

```bash theme={null}
curl https://api.caged.dev/v1/snapshots/snap-e5f6g7h8 \
  -H "Authorization: Bearer caged_sk_..."
```

## Delete Snapshot

```bash theme={null}
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.

```bash theme={null}
curl https://api.caged.dev/v1/snapshots/snap-e5f6g7h8/download \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
{
  "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.

<Warning>
  This overwrites the sandbox's current filesystem. Create a new snapshot first if you need to preserve the current state.
</Warning>

```bash theme={null}
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

| Limit                     | Value |
| ------------------------- | ----- |
| Snapshots per sandbox     | 20    |
| Total storage per account | 10 GB |
| Max single snapshot size  | 2 GB  |