# providerSnapshots (/docs/reference/api/provider-snapshots)

> Snapshots of [provider volumes](/docs/reference/api/provider-volumes), made with `providerVolumes.snapshot` and converged by the `vps.provider-resources` reconciler. Reading takes `compute:volumes:read`, deleting and restoring `compute:volumes:manage`, on `provider-snapshot/{id}`. A snapshot books no quota and bills `vps.snapshot.gib.hours` (the GiB the provider reports) from `ready` until deleted.



Snapshots of [provider volumes](/docs/reference/api/provider-volumes), made with `providerVolumes.snapshot` and converged by the `vps.provider-resources` reconciler. Reading takes `compute:volumes:read`, deleting and restoring `compute:volumes:manage`, on `provider-snapshot/{id}`. A snapshot books no quota and bills `vps.snapshot.gib.hours` (the GiB the provider reports) from `ready` until deleted.

All 4 methods are served by @better-compute/server 0.3.0.

| Method                | Kind     | Authorization                                          | Phase | Status     |
| --------------------- | -------- | ------------------------------------------------------ | ----- | ---------- |
| [`list`](#list)       | read     | `compute:volumes:read` @ `compute-tenant` + items      | v1.0  | registered |
| [`get`](#get)         | read     | `compute:volumes:read` @ `compute-provider-snapshot`   | v1.0  | registered |
| [`delete`](#delete)   | mutation | `compute:volumes:manage` @ `compute-provider-snapshot` | v1.0  | registered |
| [`restore`](#restore) | mutation | `compute:volumes:manage` @ `compute-provider-snapshot` | v1.0  | registered |

## list [#list]

`POST /api/compute/providerSnapshots/list`

Returns the tenant's snapshots in the order they were made (at most 1000), optionally of one volume. Deleted ones only with `includeDeleted`.

* **Kind:** read
* **Authorization:** `compute:volumes:read` @ `compute-tenant` + items
* **Module:** `vps`
* **Phase:** v1.0 (registered)

**Input**

| Field            | Type    | Required | Constraints                                                       |
| ---------------- | ------- | -------- | ----------------------------------------------------------------- |
| `tenantId`       | string  | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`        |
| `volumeId`       | string  |          | at most 57 characters; matches `^pvol_[0-9a-hjkmnp-tv-z]{26,52}$` |
| `includeDeleted` | boolean |          | default `false`                                                   |

## get [#get]

`POST /api/compute/providerSnapshots/get`

Returns one snapshot: its volume, name, region, size and state.

* **Kind:** read
* **Authorization:** `compute:volumes:read` @ `compute-provider-snapshot`
* **Module:** `vps`
* **Phase:** v1.0 (registered)

**Input**

| Field        | Type   | Required | Constraints                                                        |
| ------------ | ------ | -------- | ------------------------------------------------------------------ |
| `tenantId`   | string | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`         |
| `snapshotId` | string | yes      | at most 58 characters; matches `^psnap_[0-9a-hjkmnp-tv-z]{26,52}$` |

## delete [#delete]

`POST /api/compute/providerSnapshots/delete`

Marks the snapshot for deletion and returns it `deleting`; the reconciler deletes it at the provider and publishes `providerVolume.snapshot.deleted`. Deleting a snapshot being deleted returns it. A volume restored from it is not affected.

* **Kind:** mutation
* **Authorization:** `compute:volumes:manage` @ `compute-provider-snapshot`
* **Module:** `vps`
* **Phase:** v1.0 (registered)

**Input**

| Field        | Type   | Required | Constraints                                                        |
| ------------ | ------ | -------- | ------------------------------------------------------------------ |
| `tenantId`   | string | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`         |
| `snapshotId` | string | yes      | at most 58 characters; matches `^psnap_[0-9a-hjkmnp-tv-z]{26,52}$` |

## restore [#restore]

`POST /api/compute/providerSnapshots/restore`

Creates a new volume from a `ready` snapshot (`INVALID_STATE` otherwise), in the snapshot's pool and region, and returns it `pending`, as [`providerVolumes.create`](/docs/reference/api/provider-volumes) does: `sizeGiB` is at least the snapshot's (`INVALID_INPUT`; absent, the snapshot's size) and books `diskGiB`, the name is unique in the tenant, and the same `idempotencyKey` returns the same volume. The volume keeps the snapshot's filesystem: `filesystem` is `INVALID_INPUT` (a format could wipe the restored data). Only a volume snapshot this deployment made restores (the provider refuses any other, `INVALID_STATE`). A snapshot of a shared volume does not restore yet: `UNSUPPORTED` (`details.reason` `sharedRestore`). Decided on the snapshot.

* **Kind:** mutation
* **Authorization:** `compute:volumes:manage` @ `compute-provider-snapshot`
* **Module:** `vps`
* **Phase:** v1.0 (registered)

**Input**

| Field                | Type    | Required | Constraints                                                        |
| -------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `tenantId`           | string  | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`         |
| `snapshotId`         | string  | yes      | at most 58 characters; matches `^psnap_[0-9a-hjkmnp-tv-z]{26,52}$` |
| `name`               | string  | yes      | at most 42 characters; matches `^[a-z]([-a-z0-9]{0,40}[a-z0-9])?$` |
| `description`        | string  |          | at most 256 characters                                             |
| `sizeGiB`            | integer |          | 1-16384                                                            |
| `deleteWithInstance` | boolean |          | default `false`                                                    |
| `idempotencyKey`     | string  | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`         |