Snapshots

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:

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

Responses:

• 200 OK. Body: SnapshotResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: list of SnapshotResponse

Errors use the error envelope.

List snapshots

GET /v1/snapshots

Every snapshot and checkpoint of your account.

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

Responses:

• 200 OK. Body: list of SnapshotResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: SnapshotResponse

Errors use the error envelope.

Delete a snapshot

DELETE /v1/snapshots/{id}

Deletes a snapshot and frees its space.

Path parameters:

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

Responses:

• 200 OK. Body: MessageResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: InstanceResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: SnapshotResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: SnapshotTreeResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: SnapshotPullResponse

Errors use the error envelope.