# Snapshots

Keep a sandbox's disk as it is now, to roll back to or to start new sandboxes from.

`POST /v1/sandboxes/{id}/snapshots`

```shell
curl -X POST https://agental.io/v1/sandboxes/{id}/snapshots \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"before-migration"}'
```

- A snapshot is the whole disk at that moment. The sandbox may be running or stopped, and is left as it was.
- `name` is up to 64 characters.
- A snapshot outlives its sandbox. It is kept until you delete it.
- Your 10 oldest snapshots are free. Each one past them costs $1.70 a month, by the second, until you delete it. Delete an old one and the next is free.
- A deleted sandbox that has snapshots keeps its disk for them, and is billed as a stopped one until its last snapshot is deleted.
- An account with no card saved and no plan keeps its 10 free snapshots at most. Once it has either, it keeps more, paying for each one past them. When your account keeps as many as it may, one more answers `409 snapshot_limit_reached`.

## Roll back

`POST /v1/sandboxes/{id}/restore`

```json
{"snapshotId":"snap_5c1d0a9e8b7f6e42"}
```

- The sandbox is as it was when the snapshot was taken, with the same `id`, and running or stopped as it was before the call.
- What was running in it is gone, as after a stop and a start.
- Snapshots taken after that one are discarded, and listed in `discarded`.
- `409 restore_blocked` means a sandbox forked from this one after the snapshot still exists.

## A new sandbox from a snapshot

```shell
curl -X POST https://agental.io/v1/sandboxes \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: task-43" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-2","snapshotId":"snap_5c1d0a9e8b7f6e42"}'
```

The new sandbox starts with the disk as the snapshot holds it. The sandbox the snapshot was taken of is not touched, and may have been deleted. `size` defaults to the size the snapshot was taken on, and cannot be one with less disk.

## List and delete

| Call | What it does |
| --- | --- |
| `GET /v1/sandboxes/{id}/snapshots` | The snapshots of one sandbox. |
| `GET /v1/snapshots` | Every snapshot you keep, oldest first. |
| `DELETE /v1/snapshots/{id}` | Delete one. Sandboxes made from it are not affected. |

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)