# Change a snapshot

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

Change a Computer snapshot's name, note or expiry.

`POST /v1/computer/snapshot/modify`

## Parameters

- `computer` (string, required): Computer name or ID.
- `snapshot` (string, required): Snapshot name or ID.
- `name` (string): Replacement name of 1 to 63 lowercase letters, digits and hyphens. Start and end with a letter or digit.
- `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.

## Returns

- `data` (object, always present): A snapshot record and its creation or edit operation.
  - `operation` (object, always present): Snapshot operation as last read.
    - `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"`.
  - `request_id` (string, always present): Request ID for this snapshot change.
  - `snapshot` (object, always present): Snapshot's current record.
    - `automatic` (boolean, always present): Whether Heaven created the snapshot automatically.
    - `changed_since_bytes` (string | null, always present): Bytes changed since this snapshot.
    - `computer` (object, always present): Computer whose disk was snapshotted.
      - `id` (string, always present): Referenced object's stable ID.
      - `name` (string, always present): Referenced object's name.
    - `copies` (object[] | null, always present): Accessible Computers originating from this snapshot, including those later reset or restored.
      - `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.
    - `created_by` (object, always present): Who requested the snapshot.
      - `email` (string | null, always present): Their email address, or null when none is available.
      - `user_id` (string, always present): Person's user ID.
    - `data_bytes` (string | null, always present): Reported snapshot data, in bytes.
    - `data_source` (string | null, always present): Where the data-size measurement came from.
    - `disk_bytes` (string | null, always present): Logical disk size at capture, in bytes.
    - `expires_at` (string (date-time) | null, always present): When the snapshot expires. Null keeps it until explicitly deleted.
    - `id` (string, always present): Snapshot ID.
    - `kept_by` (object[] | null, always present): Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
      - `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.
    - `kept_by_computers` (object[] | null, always present): Accessible copied Computers whose disks still retain this deleted snapshot's data.
      - `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.
    - `kept_by_other_copies` (integer): Number of copied Computers you cannot access that retain this snapshot. May be omitted.
    - `name` (string, always present): Snapshot's name within its Computer.
    - `note` (string, always present): Saved note about this snapshot.
    - `observed_at` (string (date-time) | null, always present): Time the measurements were last reported.
    - `requested_at` (string (date-time), always present): When snapshot creation was requested.
    - `saved` (string | null, always present): Disk capture method: `stopped`, `flushed` or `unflushed`. Flushing does not guarantee application consistency. Null means capture is unreported.
    - `size_bytes` (string | null, always present): Storage unique to this snapshot, in bytes.
    - `state` (string, always present): Snapshot lifecycle state. `pending` awaits disk capture.
    - `taken_at` (string (date-time) | null, always present): When the disk snapshot was taken, or null before it has been reported.

## 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: `snapshot edit`.

## Examples

```sh tab="heaven CLI"
heaven snapshot edit COMPUTER SNAPSHOT
  [--name NAME]
  [--note NOTE]
  [--expires DURATION]
  [--request-id ID]
```

```sh tab="SSH"
ssh cli@heaven.dev snapshot edit COMPUTER SNAPSHOT
  [--name NAME]
  [--note NOTE]
  [--expires DURATION]
  [--request-id ID]
```

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

```json tab="MCP"
{ "tool": "snapshot_edit",
  "arguments": { "computer": "my-site", "snapshot": "before-upgrade", "note": "Before the Postgres upgrade" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "operation": {
      "completed_at": "2026-11-16T12:00:00Z",
      "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
      "created_at": "2026-11-16T12:00:00Z",
      "id": "c78b004c-b97b-4d16-a74f-85fad81cfd6f",
      "kind": "snapshot_edit",
      "state": "complete"
    },
    "request_id": "a19cd28c-0610-440e-a56d-a20233482bc9",
    "snapshot": {
      "automatic": false,
      "changed_since_bytes": null,
      "computer": {
        "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
        "name": "my-site"
      },
      "copies": [],
      "created_by": {
        "email": "you@example.com",
        "user_id": "2f8bc652-65ab-4a91-a2f0-7c5b1a899f59"
      },
      "data_bytes": null,
      "data_source": null,
      "disk_bytes": null,
      "expires_at": "2026-11-23T12:00:00Z",
      "id": "0b248207-e03b-47d5-a94d-ad4d6fa8592a",
      "kept_by": null,
      "kept_by_computers": null,
      "name": "before-upgrade",
      "note": "Before the Postgres upgrade",
      "observed_at": null,
      "requested_at": "2026-11-16T12:00:00Z",
      "saved": null,
      "size_bytes": null,
      "state": "ready",
      "taken_at": null
    }
  }
}
```
