Capture a snapshot

POST

sandboxes

{id}

snapshots

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/snapshots" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "python-ready",
  "retentionSeconds": 86400
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
snapshot = sandbox.snapshot(name="python-ready", retention_seconds=86400)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const snapshot = await sandbox.snapshot({ name: "python-ready", retentionSeconds: 86400 });

{
  "snapshotID": "<string>",
  "templateID": "<string>",
  "buildID": "<string>",
  "status": "<string>",
  "name": "<string>",
  "names": [
    "<string>"
  ]
}

Authentication

Send your scoped bearer token in the Authorization: Bearer <BEAD_TOKEN> header, or send your API key in X-API-Key.

Parameters

string

required

Machine identifier returned by creation.

string

Caller-generated durable retry key: lowercase ASCII letters, digits, and hyphens only. Reuse the same key and body after a connection failure. Minimum length: 1. Maximum length: 255.

Request body

The JSON body is required.

string

default:"snapshot"

Display name for this snapshot.

boolean

default:false

Explicitly consent to copying configured credentials into the snapshot.

boolean

default:true

Restore retained memory; false is rejected with 501 unsupported_feature in this deployment.

integer

Retention in seconds; omit for no scheduled expiry. Explicit values must be at least 60. Minimum: 60.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/snapshots" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "python-ready",
  "retentionSeconds": 86400
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
snapshot = sandbox.snapshot(name="python-ready", retention_seconds=86400)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const snapshot = await sandbox.snapshot({ name: "python-ready", retentionSeconds: 86400 });

Response

202

Capture queued; poll GET /snapshots/{id} until ready.

string

required

Snapshot identifier to poll or use as a template.

string

required

Template identifier for creating machines from this snapshot.

string

required

UUID of this immutable snapshot build.

string

required

Capture is queued for publication. Allowed values: "pending".

string

required

Display name supplied for the snapshot.

string[]

required

Names associated with this snapshot.

Errors

Status	Meaning
400	Invalid request values, unsupported bounds, or malformed JSON.
401	Authentication credential is missing or rejected.
402	Insufficient prepaid credit (`insufficient_credit`), or snapshot storage billing is unavailable.
403	The credential lacks the required scope.
404	The requested resource does not exist or is outside your organization.
409	Request key reused with a different body (`idempotency_request_mismatch`), or resource ownership/state conflicts.
413	Request body exceeds the route limit.
429	Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next_action and Retry-After when present.
503	Service or persistence is temporarily unavailable.

curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/snapshots" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "python-ready",
  "retentionSeconds": 86400
}
JSON

# sandbox is returned by Sandbox.create or Sandbox.connect.
snapshot = sandbox.snapshot(name="python-ready", retention_seconds=86400)

// sandbox is returned by Sandbox.create or Sandbox.connect.
const snapshot = await sandbox.snapshot({ name: "python-ready", retentionSeconds: 86400 });

{
  "snapshotID": "<string>",
  "templateID": "<string>",
  "buildID": "<string>",
  "status": "<string>",
  "name": "<string>",
  "names": [
    "<string>"
  ]
}

Start here

Endpoints

Capture a snapshot

Authentication

Parameters

Request body

Response

202

Errors

​Authentication

​Parameters

​Request body

​Response

​202

​Errors

Authentication

Parameters

Request body

Response

202

Errors