Snapshots

The Snapshots API lets you capture and restore point-in-time snapshots of a sandbox session. Snapshots preserve the full state of the session, including filesystem contents and running processes, so you can roll back to a known-good state at any time.

To obtain your authentication credentials, install the Release CLI and run release auth login. The CLI stores credentials in ~/.release.yaml.

---

State Lifecycle

Snapshots progress through the following states:

creating -> ready | failed

When a snapshot is being restored, its state transitions to:

restoring -> ready | failed

State	Description
creating	Snapshot is being captured
ready	Snapshot is available for use
failed	Snapshot creation or restoration failed
restoring	Snapshot is being restored to the session

---

Create Snapshot

Creates a new snapshot of the current session state.

Endpoint

POST https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/snapshots

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Content-Type	application/json
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Status Codes

Code	Description
201	Snapshot creation started
401	Unauthorized — invalid or missing credentials
404	Session not found
422	Invalid session state for snapshotting

Response Body

Field	Type	Description
id	string (hashid)	Unique identifier for the snapshot
state	string	One of: creating, ready, failed, restoring
created_at	string (ISO 8601)	When the snapshot was created
updated_at	string (ISO 8601)	When the snapshot was last updated

Example Responses

201 Created

{
  "id": "snP7kW",
  "state": "creating",
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

---

List Snapshots

Returns all snapshots for a session.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/snapshots

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID

Status Codes

Code	Description
200	Returns array of snapshots
401	Unauthorized — invalid or missing credentials
404	Session not found

Response Body

Returns an array of snapshot objects.

Field	Type	Description
id	string (hashid)	Unique identifier for the snapshot
state	string	One of: creating, ready, failed, restoring
created_at	string (ISO 8601)	When the snapshot was created
updated_at	string (ISO 8601)	When the snapshot was last updated

Example Responses

200 OK

[
  {
    "id": "snP7kW",
    "state": "ready",
    "created_at": "2026-06-01T12:00:00Z",
    "updated_at": "2026-06-01T12:00:30Z"
  },
  {
    "id": "snQ2mR",
    "state": "creating",
    "created_at": "2026-06-01T14:00:00Z",
    "updated_at": "2026-06-01T14:00:00Z"
  }
]

---

Get Snapshot

Returns a single snapshot by ID.

Endpoint

GET https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/snapshots/{snapId}

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value
Accept	application/json

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID
snapId	string (hashid)	Yes	The snapshot ID

Status Codes

Code	Description
200	Returns the snapshot
401	Unauthorized — invalid or missing credentials
404	Session or snapshot not found

Response Body

Field	Type	Description
id	string (hashid)	Unique identifier for the snapshot
state	string	One of: creating, ready, failed, restoring
created_at	string (ISO 8601)	When the snapshot was created
updated_at	string (ISO 8601)	When the snapshot was last updated

Example Responses

200 OK

{
  "id": "snP7kW",
  "state": "ready",
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:30Z"
}

404 Not Found

{
  "errors": [
    {
      "code": "not_found",
      "message": "Snapshot not found"
    }
  ]
}

---

Restore Snapshot

Restores a session to the state captured by a snapshot. The snapshot must be in ready state.

Endpoint

POST https://backend-{handle}-envs.gcp.release.com/ai/accounts/{accountId}/sandbox_sessions/{id}/snapshots/{snapId}/restore

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Path Parameters

Name	Type	Required	Description
accountId	string (hashid)	Yes	The Release account ID
id	string (hashid)	Yes	The sandbox session ID
snapId	string (hashid)	Yes	The snapshot ID

Status Codes

Code	Description
200	Snapshot restoration started
401	Unauthorized — invalid or missing credentials
404	Session or snapshot not found
422	Snapshot is not in ready state or session state does not allow restore

Response Body

Returns the snapshot object with its state set to restoring.

Field	Type	Description
id	string (hashid)	Unique identifier for the snapshot
state	string	One of: creating, ready, failed, restoring
created_at	string (ISO 8601)	When the snapshot was created
updated_at	string (ISO 8601)	When the snapshot was last updated

Example Responses

200 OK

{
  "id": "snP7kW",
  "state": "restoring",
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T16:00:00Z"
}

422 Unprocessable Entity

{
  "errors": [
    {
      "code": "invalid_state",
      "message": "Snapshot is not in ready state"
    }
  ]
}