---
title: "Create a snapshot for an instance"
method: POST
path: "/instances/{id}/snapshots"
---

# Create a snapshot for an instance

`POST /instances/{id}/snapshots`

## Path parameters

- `id` string, required

## Request body

- CreateSnapshotRequest
  - `kind` 'Standby' | 'Stopped', required — Snapshot capture kind
  - `name` string — Optional snapshot name (lowercase letters, digits, and dashes only; cannot start or end with a dash)
  - `tags` Tags — User-defined key-value tags.
  - `compression` SnapshotCompressionConfig
    - `enabled` boolean, required — Enable snapshot memory compression
    - `algorithm` 'zstd' | 'lz4' — Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
    - `level` integer — Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.

## Response `201`

Snapshot created

- Snapshot
  - `id` string, required — Auto-generated unique snapshot identifier
  - `name` string, nullable — Optional human-readable snapshot name (unique per source instance)
  - `kind` 'Standby' | 'Stopped', required — Snapshot capture kind
  - `tags` Tags — User-defined key-value tags.
  - `source_instance_id` string, required — Source instance ID at snapshot creation time
  - `source_instance_name` string, required — Source instance name at snapshot creation time
  - `source_hypervisor` 'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz', required — Source instance hypervisor at snapshot creation time
  - `created_at` string, date-time, required — Snapshot creation timestamp
  - `size_bytes` integer, required — Total payload size in bytes
  - `compression_state` 'none' | 'compressing' | 'compressed' | 'error' — Compression status of the snapshot payload memory file
  - `compression_error` string, nullable — Compression error message when compression_state is error
  - `compression` SnapshotCompressionConfig
    - `enabled` boolean, required — Enable snapshot memory compression
    - `algorithm` 'zstd' | 'lz4' — Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
    - `level` integer — Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.
  - `compressed_size_bytes` integer, nullable — Compressed memory payload size in bytes
  - `uncompressed_size_bytes` integer, nullable — Uncompressed memory payload size in bytes

## Other responses

- `400` — Bad request - invalid snapshot request
- `404` — Source instance not found
- `409` — Conflict - invalid state or duplicate snapshot name
- `500` — Internal server error
- `501` — Not implemented - operation unsupported by source hypervisor

## Changes

- **2026-03-23** `8251e13b6a8e` — 6 info
  - added the new optional request property `compression`
  - added the optional property `compressed_size_bytes` to the response with the `201` status
  - added the optional property `compression` to the response with the `201` status
  - added the optional property `compression_error` to the response with the `201` status
  - …2 more
- **2026-03-09** `d3b8f05f7a0f` — 2 warning, 2 info
  - removed the request property `metadata`
  - removed the optional property `metadata` from the response with the `201` status
  - added the new optional request property `tags`
  - added the optional property `tags` to the response with the `201` status
- **2026-03-07** `48572ed07140` — 2 info
  - added the new optional request property `metadata`
  - added the optional property `metadata` to the response with the `201` status
- **2026-03-07** `ef3a9825726e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kernel/apis/hypeman-api/changes/instances/:id/snapshots/post.md)

---

[API](https://skmtc.dev/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.dev/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/hypeman-api/revisions/b4642bb950dc/schema)