# Restore a pool snapshot

URL: https://heaven.dev/docs/reference/pool-snapshots/restore
Updated: 2026-11-21

Restore the disks of the Computers recorded in a pool snapshot and start them. Heaven saves their current disks as snapshots first. Computers created later stay as they are, and the result reports any that were deleted. The pool must be running.

`POST /v1/pool/snapshot/modify`

## Parameters

- `pool` (string, required): Pool name or ID.
- `snapshot` (string, required): Snapshot name or ID.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): A pool snapshot change and its per-Computer operations.
  - `deleted_since` (object[]): Computers deleted since capture, which cannot be restored in place. Computers created since capture are unchanged. May be omitted.
    - `items` (object): A Computer, pool or snapshot reference.
      - `id` (string, always present): Referenced object's stable ID.
      - `name` (string, always present): Referenced object's name.
  - `operation` (object, always present): Group tracking the Computer operations.
    - `completed_at` (string (date-time)): When the group finished. Absent while unfinished. May be omitted.
    - `created_at` (string (date-time), always present): When the grouped change was accepted.
    - `id` (string, always present): Group ID for `operation view`.
    - `kind` (string, always present): Grouped change.
    - `message` (string): An explanation of the group's progress or failure. May be omitted.
    - `operations` (object[] | null, always present): Member Computer operations.
      - `items` (object): An accepted change to one Computer. Work continues after the request disconnects.
        - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
        - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
        - `computer_id` (string, always present): Computer's stable ID.
        - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
        - `error_code` (string): Recorded failure code. May be omitted.
        - `id` (string, always present): Operation ID for `operation view`.
        - `kind` (string, always present): Change being tracked.
        - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
        - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
    - `pool_id` (string): Pool this change concerns. May be omitted.
    - `state` (string, always present): `accepted` while work remains, `complete` when all work succeeds, or `failed` when a step fails or a member operation fails or is superseded. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
    - `steps` (object[]): Other steps, in execution order. May be omitted.
      - `items` (object): A step in a grouped change outside its Computer operations.
        - `kind` (string, always present): Action taken by this step.
        - `message` (string): Progress or failure details for this step. May be omitted.
        - `pool_id` (string): Affected pool's ID. May be omitted.
        - `state` (string, always present): Step's recorded progress or outcome.
        - `subject` (string): Affected object, such as an organization being left. May be omitted.
    - `subject` (string): Other object the change concerns, such as a pool snapshot's name. May be omitted.
  - `pool_snapshot` (object, always present): Pool snapshot being changed.
    - `id` (string, always present): Pool snapshot's ID.
    - `name` (string, always present): Pool snapshot's name.
    - `pool` (object, always present): Pool's ID and name.
      - `id` (string, always present): Referenced object's stable ID.
      - `name` (string, always present): Referenced object's name.
  - `request_id` (string, always present): Request ID for this pool snapshot change.
  - `results` (object[] | null, always present): Each Computer's operation or refusal.
    - `items` (object): One Computer's part of a pool snapshot change.
      - `computer` (object, always present): Computer whose disk is affected.
        - `id` (string, always present): Referenced object's stable ID.
        - `name` (string, always present): Referenced object's name.
      - `error` (object): Why this Computer's part was refused. May be omitted.
        - `action` (object): A suggested command addressing the problem. May be omitted.
          - `command` (string, always present): Command's catalog name.
          - `line` (string, always present): Complete suggested command line.
        - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
        - `message` (string, always present): What happened and any action needed from you.
        - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
        - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
        - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
        - `url` (string): Payment page for a payment-required response. May be omitted.
      - `operation` (object): Accepted operation for this Computer. May be omitted.
        - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
        - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
        - `computer_id` (string, always present): Computer's stable ID.
        - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
        - `error_code` (string): Recorded failure code. May be omitted.
        - `id` (string, always present): Operation ID for `operation view`.
        - `kind` (string, always present): Change being tracked.
        - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
        - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `snapshot` (object): Its individual snapshot, when one is associated with the result. May be omitted.
        - `id` (string, always present): Referenced object's stable ID.
        - `name` (string, always present): Referenced object's name.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `pool snapshot restore`.

## Examples

```sh tab="heaven CLI"
heaven pool snapshot restore POOL SNAPSHOT
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool snapshot restore POOL SNAPSHOT
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/pool/snapshot/modify \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"action": "restore", "pool": "web", "snapshot": "before-upgrade"}'
```

```json tab="MCP"
{ "tool": "pool_snapshot_restore",
  "arguments": { "pool": "web", "snapshot": "before-upgrade" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "operation": {
      "created_at": "2026-11-16T12:00:00Z",
      "id": "04808676-9d2e-440c-ab22-0cda5425665d",
      "kind": "pool snapshot restore",
      "operations": [
        {
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "9be8be60-7489-45c2-a2b9-635b46daad04",
          "kind": "rollback",
          "state": "accepted"
        },
        {
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "75253a08-c0ab-41d1-a516-3f7ef0500577",
          "kind": "rollback",
          "state": "accepted"
        }
      ],
      "pool_id": "pool-9411755c28291adc",
      "state": "accepted",
      "subject": "before-upgrade"
    },
    "pool_snapshot": {
      "id": "96ab68c9-913b-4b56-aa00-c28a160ea44c",
      "name": "before-upgrade",
      "pool": {
        "id": "pool-9411755c28291adc",
        "name": "web"
      }
    },
    "request_id": "39ddc578-3863-456b-a0b0-54365759fb40",
    "results": [
      {
        "computer": {
          "id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "name": "my-api"
        },
        "operation": {
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "75253a08-c0ab-41d1-a516-3f7ef0500577",
          "kind": "rollback",
          "state": "accepted"
        },
        "snapshot": {
          "id": "8fc9c407-1ac3-4077-a3ec-346297d2c254",
          "name": "before-upgrade"
        }
      },
      {
        "computer": {
          "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "name": "my-site"
        },
        "operation": {
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "9be8be60-7489-45c2-a2b9-635b46daad04",
          "kind": "rollback",
          "state": "accepted"
        },
        "snapshot": {
          "id": "5f7cc10a-7ddf-46fd-a83a-3e951e5b3663",
          "name": "before-upgrade"
        }
      }
    ]
  }
}
```
