Snapshots
A snapshot is an account-owned checkpoint you can restore into new sandboxes, even after deleting its source. It is separate from pause, resume and fork: capture briefly freezes a running source and then resumes it.
Base URL: https://api.sb.createos.sh. Authenticate with the owner's user credential in X-Api-Key. Sandbox-scoped access tokens cannot create, list, inspect or delete snapshots (403). Responses use JSend.
Choose a capture type
| Type | Preserves | Restore sizing |
|---|---|---|
disk | Root-disk contents; starts a fresh runtime without saved memory or running processes | May choose a different shape and a larger allowed disk size; cannot shrink the disk. |
full | Root disk, memory and execution state | Must retain captured vCPU count, memory and disk size. |
Only running sandboxes without attached external disks can be captured. Resume a paused source and detach external disks before capture. A snapshot does not copy S3 bucket contents. Quiesce application writes when you need an application-consistent checkpoint; reconnect external services after a full restore.
Pause, deletion, configuration changes and conflicting disk operations can return 409 while capture still needs the source. Poll the snapshot until it becomes ready before restoring it. A failed snapshot cannot be restored.
POST /v1/sandboxes/{id}/snapshots
| Field | Required | Description |
|---|---|---|
type | Yes | disk or full. |
name | No | Display label, not a lookup key. Up to 63 ASCII letters, digits, underscores or hyphens; starts and ends with a letter or digit. Names need not be unique. |
curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/snapshots" \
-H "X-Api-Key: $CREATEOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"disk","name":"configured-workspace"}'Returns 202 Accepted, a snapshot view, and X-Poll-After: 2. Save data.id (prefix snap_) and poll GET /v1/snapshots/{snapshot}. Acceptance does not mean capture is complete.
The per-user quota is five snapshots across both types, counting creating, ready and deleting; failed snapshots do not count. Concurrent requests or regional replication can temporarily exceed the quota. Delete an existing ready or failed snapshot when appropriate before retrying a quota rejection.
Errors: 400 invalid body, 403 sandbox-scoped credential, 404 source not found or not owned, 409 source not running, external disks attached or source busy, 429 snapshot quota/rate limit, 503 capture temporarily unavailable.
GET /v1/snapshots
List the caller's snapshots. limit defaults to 50 (maximum 500); offset defaults to 0. Results use the usual data.data[] and data.pagination envelope.
curl 'https://api.sb.createos.sh/v1/snapshots?limit=50&offset=0' \
-H "X-Api-Key: $CREATEOS_API_KEY"GET /v1/snapshots/{snapshot}
Retrieve an owned snapshot by ID. A missing or unowned snapshot returns 404.
| Field | Meaning |
|---|---|
id, name | Stable ID and optional non-unique display label. |
sandbox_id | Original source ID; the source may have been deleted. |
type | disk or full. |
status | creating, ready, failed or deleting. |
created_at, ready_at | Creation timestamp and optional readiness timestamp. |
shape, vcpu, mem_mib, disk_mib | Captured sizing. |
size_bytes | Stored snapshot artifact size in bytes. |
Restore with POST /v1/sandboxes
curl -X POST https://api.sb.createos.sh/v1/sandboxes \
-H "X-Api-Key: $CREATEOS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"snapshot_id":"snap_REPLACE_WITH_READY_ID","name":"restored-workspace"}'Supply an owned, ready snapshot_id and omit rootfs. Shape and disk size default to the captured values. For a disk snapshot, optional shape and disk_mib overrides must satisfy the catalog and plan limits. For a full snapshot, sizing must match the capture exactly. Normal creation credit and plan gates still apply.
The result is an independent sandbox with a new ID. Create and get responses include snapshot_id for restored sandboxes. The snapshot remains reusable; restoring does not consume it or require the original sandbox to exist.
Errors: 400 incompatible sizing or rootfs combined with snapshot_id, 404 missing/unowned snapshot, 409 snapshot not ready, plus ordinary sandbox-create errors.
DELETE /v1/snapshots/{snapshot}
curl -X DELETE "https://api.sb.createos.sh/v1/snapshots/$SNAPSHOT_ID" \
-H "X-Api-Key: $CREATEOS_API_KEY"Deletes an owned ready or failed snapshot from API listings and lookups. Returns 202 Accepted with data.id and data.status: "deleting". A capture still in progress returns 409.
Deletion does not immediately erase stored artifacts: they are retained so in-flight restores can finish. A region with replication lag may briefly accept a restore after deletion. Already-restored sandboxes remain independent. Do not treat this operation as a secure-erasure guarantee.
CLI and SDK
Use createos sandbox snapshot or the SDK snapshot recipe. Snapshot commands take IDs for lookup and deletion, even if a display name was supplied at capture.