# Change a pool snapshot

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

Change a pool snapshot's name, note or expiry. The same edits apply to the individual Computer snapshots.

`POST /v1/pool/snapshot/modify`

## Parameters

- `pool` (string, required): Pool name or ID.
- `snapshot` (string, required): Snapshot name or ID.
- `name` (string): Replacement name for the pool snapshot and its Computer snapshots.
- `note` (string): One-line snapshot note of up to 200 bytes. An empty string clears it.
- `expires` (string): New retention measured from the time of editing, from 1d to 365d or never. Omit to keep 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): An edited pool snapshot and its per-Computer results.
  - `pool_snapshot` (object, always present): Edited pool snapshot.
    - `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.
  - `results` (object[] | null, always present): Edit's per-Computer results.
    - `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 edit`.

## Examples

```sh tab="heaven CLI"
heaven pool snapshot edit POOL SNAPSHOT
  [--name NAME]
  [--note NOTE]
  [--expires DURATION]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev pool snapshot edit POOL SNAPSHOT
  [--name NAME]
  [--note NOTE]
  [--expires DURATION]
  [--organization ORGANIZATION]
```

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

```json tab="MCP"
{ "tool": "pool_snapshot_edit",
  "arguments": { "pool": "web", "snapshot": "before-upgrade", "note": "Before the Postgres upgrade" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "pool_snapshot": {
      "id": "ba8a0f10-5547-4901-a566-97d4d761e1e4",
      "name": "before-upgrade",
      "pool": {
        "id": "pool-c2d02083ac8ff59c",
        "name": "web"
      }
    },
    "results": [
      {
        "computer": {
          "id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "name": "my-api"
        },
        "operation": {
          "completed_at": "2026-11-16T12:00:00Z",
          "computer_id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "5601cbea-a7ae-461e-a271-061b976cb247",
          "kind": "snapshot_edit",
          "state": "complete"
        },
        "snapshot": {
          "id": "c3fbbbaa-edbf-4de2-aca0-f104f1ab9afd",
          "name": "before-upgrade"
        }
      },
      {
        "computer": {
          "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "name": "my-site"
        },
        "operation": {
          "completed_at": "2026-11-16T12:00:00Z",
          "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
          "created_at": "2026-11-16T12:00:00Z",
          "id": "856eba5f-e095-40c1-ac2c-4da4cd450e33",
          "kind": "snapshot_edit",
          "state": "complete"
        },
        "snapshot": {
          "id": "f3e1746a-984b-44da-a2c2-6effae4d8464",
          "name": "before-upgrade"
        }
      }
    ]
  }
}
```
