Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt

Use this file to discover all available pages before exploring further.

Snapshots are persistent, point-in-time captures of sandbox state stored as OCI images. They are independent of the source sandbox — once created, a snapshot outlives the sandbox it was captured from and can be used to provision new sandboxes by passing snapshotId to POST /v1/sandboxes. Snapshot creation is asynchronous: the source sandbox remains running while the runtime captures state, and the snapshot transitions from Creating → Ready (or Failed) in the background.
For a complete walkthrough of pause, snapshot, and resume patterns, see Pause and Resume guide.
All endpoints share the base URL http://localhost:8080/v1 and require the OPEN-SANDBOX-API-KEY header.

​
POST /v1/sandboxes//snapshots

Creates a persistent snapshot from the current state of a running sandbox. The source sandbox must be in Running state. Returns 202 Accepted with a snapshot object in Creating state — poll GET /v1/snapshots/{snapshotId} to track progress. Auth: OPEN-SANDBOX-API-KEY header required.

​
Path Parameters

​
sandboxId
string
required
Unique identifier of the source sandbox. Must be in Running state.

​
Request Body (optional)

​
name
string
Optional human-readable name for the snapshot. Minimum 1 character.

​
Response — 202 Accepted

​
id
string
required
Unique snapshot identifier.
​
sandboxId
string
required
Source sandbox identifier used to create this snapshot.
​
name
string
Optional human-readable snapshot name.
​
status
object
required
Snapshot lifecycle status.
​
createdAt
string
required
RFC 3339 snapshot creation timestamp.

​
Example

curl -X POST http://localhost:8080/v1/sandboxes/sbx_abc123/snapshots \
  -H "OPEN-SANDBOX-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}'

​
GET /v1/snapshots

Lists all snapshots with optional filtering by source sandbox ID and lifecycle state, plus pagination support. Auth: OPEN-SANDBOX-API-KEY header required.

​
Query Parameters

​
sandboxId
string
Filter snapshots by source sandbox identifier.
​
state
string
Filter by snapshot lifecycle state. Pass multiple times for OR logic. Example: ?state=Ready&state=Failed.
​
page
integer
Page number for pagination (minimum 1, default 1).
​
pageSize
integer
Number of items per page (minimum 1, default 20).

​
Response — 200 OK

​
items
array
required
Array of snapshot objects.
​
pagination
object
required

​
Example

curl "http://localhost:8080/v1/snapshots?state=Ready&page=1&pageSize=20" \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

​
GET /v1/snapshots/

Returns the current state and metadata for a single snapshot. Auth: OPEN-SANDBOX-API-KEY header required.

​
Path Parameters

​
snapshotId
string
required
Unique snapshot identifier.

​
Response — 200 OK

​
id
string
required
Unique snapshot identifier.
​
sandboxId
string
required
Source sandbox identifier.
​
name
string
Optional human-readable snapshot name.
​
status
object
required
Snapshot lifecycle status with state, reason, message, and lastTransitionAt.
​
createdAt
string
required
RFC 3339 creation timestamp.

​
Example

curl http://localhost:8080/v1/snapshots/snap_xyz789 \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

​
DELETE /v1/snapshots/

Deletes a snapshot by ID. Snapshots still in Creating state cannot be deleted — wait for Ready or Failed first. Returns 204 No Content on success. Auth: OPEN-SANDBOX-API-KEY header required.
For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata and coordination resources but does not guarantee removal of the pushed OCI image from the configured registry. Apply registry retention or garbage collection policies separately for image lifecycle cleanup.

​
Path Parameters

​
snapshotId
string
required
Unique snapshot identifier.

​
Example

curl -X DELETE http://localhost:8080/v1/snapshots/snap_xyz789 \
  -H "OPEN-SANDBOX-API-KEY: your-api-key"

​
Snapshot Lifecycle States

StateDescription
CreatingSnapshot creation accepted; runtime capture is in progress.
ReadySnapshot is available for restoring sandboxes.
DeletingSnapshot deletion requested; cleanup is in progress.
FailedSnapshot creation failed. Check status.message for details.
After a snapshot reaches Ready, restore it by passing "snapshotId": "snap_xyz789" in the POST /v1/sandboxes request body.

Build docs developers (and LLMs) love

Get started for freeTalk to us