> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Snapshots

> Named snapshots and automatic checkpoints: list, create, restore and delete them.

Named snapshots and automatic checkpoints: list, create, restore and delete them.

## Create a named snapshot

`POST /v1/instances/{name}/snapshots`

Takes a named snapshot of the Kiste's disk now. Named snapshots are kept until you delete them, also after the Kiste is deleted, and are copied off-site like automatic checkpoints.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

```bash
curl -sS -X POST "https://kiste.run/v1/instances/review-42/snapshots" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"before-upgrade"}'
```

**Request body:** [CreateSnapshotRequest](https://docs.kiste.run/api/schemas.md#createsnapshotrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |

**Responses:**

- `200` OK. Body: [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List a Kiste's snapshots

`GET /v1/instances/{name}/snapshots`

The named snapshots and automatic checkpoints of one Kiste, newest first, with their off-site state.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

```bash
curl -sS "https://kiste.run/v1/instances/review-42/snapshots" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List snapshots

`GET /v1/snapshots`

Every snapshot and checkpoint of your account.

```bash
curl -sS "https://kiste.run/v1/snapshots" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get a snapshot

`GET /v1/snapshots/{id}`

One snapshot: size, how it was taken (`consistency`), whether a local copy is present and its off-site state (`remote`).

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS "https://kiste.run/v1/snapshots/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Delete a snapshot

`DELETE /v1/snapshots/{id}`

Deletes a snapshot and frees its space.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X DELETE "https://kiste.run/v1/snapshots/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [MessageResponse](https://docs.kiste.run/api/schemas.md#messageresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Restore a snapshot

`POST /v1/snapshots/{id}/restore`

Creates a new, independent Kiste with the given `name` from a snapshot. The source Kiste, if it still exists, is not touched. When only the off-site copy exists the Kiste starts right away and fetches its disk in the background; `from_offsite` forces that path, which proves the off-site copy restores.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X POST "https://kiste.run/v1/snapshots/ID/restore" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"review-42-restored"}'
```

**Request body:** [RestoreSnapshotRequest](https://docs.kiste.run/api/schemas.md#restoresnapshotrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from_offsite` | boolean | no | Restore from the off-site copy even where the local copy exists: proves the off-site copy restores (it boots lazily from it). |
| `name` | string | yes |  |

**Responses:**

- `200` OK. Body: [InstanceResponse](https://docs.kiste.run/api/schemas.md#instanceresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get the newest snapshot

`GET /v1/snapshots/latest`

The newest ready snapshot of a Kiste (`instance`) or of a snapshot lineage (`lineage_id`).

**Query parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `instance` | string | no | Kiste name. |
| `lineage_id` | string | no | Lineage of snapshots that share an origin. |

```bash
curl -sS "https://kiste.run/v1/snapshots/latest" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [SnapshotResponse](https://docs.kiste.run/api/schemas.md#snapshotresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get the snapshot lineage

`GET /v1/snapshots/tree`

The ordered lineage of snapshots of a Kiste or lineage: which snapshot was taken from which.

**Query parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `instance` | string | no | Kiste name. |
| `lineage_id` | string | no | Lineage of snapshots that share an origin. |

```bash
curl -sS "https://kiste.run/v1/snapshots/tree" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [SnapshotTreeResponse](https://docs.kiste.run/api/schemas.md#snapshottreeresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get off-site restore details

`GET /v1/snapshots/{id}/pull`

Whether a snapshot can be restored from its off-site copy, and its stored size there.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS "https://kiste.run/v1/snapshots/ID/pull" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [SnapshotPullResponse](https://docs.kiste.run/api/schemas.md#snapshotpullresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Related topics

- [Overview](https://docs.kiste.run/api.md)
- [Conventions](https://docs.kiste.run/api/conventions.md)
- [Kisten](https://docs.kiste.run/api/instances.md)
- [Commands](https://docs.kiste.run/api/commands.md)
- [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)
- [Desktop](https://docs.kiste.run/api/desktop.md)
- [Kiste Stream](https://docs.kiste.run/api/stream.md)
- [Images and environments](https://docs.kiste.run/api/images.md)
- [Events, webhooks and alerts](https://docs.kiste.run/api/events.md)
- [Account and access](https://docs.kiste.run/api/account.md)
- [Sign-in and platform](https://docs.kiste.run/api/platform.md)
- [Schemas](https://docs.kiste.run/api/schemas.md)
- Previous: [Commands](https://docs.kiste.run/api/commands.md)
- Next: [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)