# Snapshot a pool

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

Save a disk snapshot of each Computer in a pool. The set contains disk contents only. Account management permission and a name available for the pool and its Computers are required. Read the returned operation with `operation view` for the result.

`POST /v1/pool/snapshot/create`

## Parameters

- `pool` (string, required): Pool name or ID.
- `name` (string): Name for the pool snapshot and its Computer snapshots. Omit to generate a name based on the current time.
- `note` (string): One-line snapshot note of up to 200 bytes. An empty string clears it.
- `expires` (string): Snapshot retention in whole days from 1d to 365d, or never. Creation defaults to 7d. An edit without this field keeps the current expiry.
- `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 create`.

## Examples

```sh tab="heaven CLI"
heaven pool snapshot create POOL [NAME]
  [--note NOTE]
  [--expires DURATION]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool snapshot create POOL [NAME]
  [--note NOTE]
  [--expires DURATION]
  [--request-id ID]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/pool/snapshot/create \
  -H "Authorization: Bearer $HEAVEN_API_KEY" \
  --json '{"pool": "web", "name": "nightly", "expires": "30d"}'
```

```json tab="MCP"
{ "tool": "pool_snapshot_create",
  "arguments": { "pool": "web", "name": "nightly", "expires": "30d" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "operation": {
      "created_at": "2026-11-16T12:00:00Z",
      "id": "39ae0506-1bc7-4a94-aae5-718837c6a4f8",
      "kind": "pool snapshot create",
      "operations": [
        {
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "fbe738d6-5e4d-4dc2-a262-7f3e228ef564",
          "kind": "snapshot",
          "state": "accepted"
        },
        {
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "eb634f4d-4500-4da2-afe9-97b1a29b2cac",
          "kind": "snapshot",
          "state": "accepted"
        }
      ],
      "pool_id": "pool-309ecc9609a1ba92",
      "state": "accepted",
      "subject": "nightly"
    },
    "pool_snapshot": {
      "id": "bf5c48e6-3aaa-4661-a47c-0630b28ab431",
      "name": "nightly",
      "pool": {
        "id": "pool-309ecc9609a1ba92",
        "name": "web"
      }
    },
    "request_id": "eadc376a-467b-4c0b-abaf-eba505f1c0e6",
    "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": "eb634f4d-4500-4da2-afe9-97b1a29b2cac",
          "kind": "snapshot",
          "state": "accepted"
        },
        "snapshot": {
          "id": "b68c530d-1cca-43a6-aebd-f60cf031ef8e",
          "name": "nightly"
        }
      },
      {
        "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": "fbe738d6-5e4d-4dc2-a262-7f3e228ef564",
          "kind": "snapshot",
          "state": "accepted"
        },
        "snapshot": {
          "id": "1cb8a9eb-fed2-47ac-aa21-2c517a9f6671",
          "name": "nightly"
        }
      }
    ]
  }
}
```
