Skip to content
hypeman
Get started
API Reference
Instances
Snapshots

Create a snapshot for an instance

post/instances/{id}/snapshots

Create a snapshot for an instance

Path ParametersExpand Collapse
id: string
Body ParametersExpand Collapse
kind: SnapshotKind

Snapshot capture kind

Accepts one of the following:
"Standby"
"Stopped"
compression: optional SnapshotCompressionConfig { enabled, algorithm, level }

Compression settings to use for this snapshot. Overrides instance and server defaults.

enabled: boolean

Enable snapshot memory compression

algorithm: optional "zstd" or "lz4"

Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.

Accepts one of the following:
"zstd"
"lz4"
level: optional number

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.

minimum0
maximum19
name: optional string

Optional snapshot name (lowercase letters, digits, and dashes only; cannot start or end with a dash)

maxLength63
tags: optional map[string]

User-defined key-value tags.

ReturnsExpand Collapse
Snapshot = object { id, created_at, kind, 11 more }
id: string

Auto-generated unique snapshot identifier

created_at: string

Snapshot creation timestamp

formatdate-time
kind: SnapshotKind

Snapshot capture kind

Accepts one of the following:
"Standby"
"Stopped"
size_bytes: number

Total payload size in bytes

formatint64
source_hypervisor: "cloud-hypervisor" or "firecracker" or "qemu" or "vz"

Source instance hypervisor at snapshot creation time

Accepts one of the following:
"cloud-hypervisor"
"firecracker"
"qemu"
"vz"
source_instance_id: string

Source instance ID at snapshot creation time

source_instance_name: string

Source instance name at snapshot creation time

compressed_size_bytes: optional number

Compressed memory payload size in bytes

formatint64
compression: optional SnapshotCompressionConfig { enabled, algorithm, level }
enabled: boolean

Enable snapshot memory compression

algorithm: optional "zstd" or "lz4"

Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.

Accepts one of the following:
"zstd"
"lz4"
level: optional number

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.

minimum0
maximum19
compression_error: optional string

Compression error message when compression_state is error

compression_state: optional "none" or "compressing" or "compressed" or "error"

Compression status of the snapshot payload memory file

Accepts one of the following:
"none"
"compressing"
"compressed"
"error"
name: optional string

Optional human-readable snapshot name (unique per source instance)

tags: optional map[string]

User-defined key-value tags.

uncompressed_size_bytes: optional number

Uncompressed memory payload size in bytes

formatint64
Create a snapshot for an instance
curl http://localhost:8080/instances/$ID/snapshots \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HYPEMAN_API_KEY" \
    -d '{
          "kind": "Standby",
          "name": "pre-upgrade",
          "tags": {
            "team": "backend",
            "env": "staging"
          }
        }'
{
  "id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "created_at": "2026-03-06T13:56:11Z",
  "kind": "Standby",
  "size_bytes": 104857600,
  "source_hypervisor": "cloud-hypervisor",
  "source_instance_id": "qilviffnqzck2jrim1x6s2b1",
  "source_instance_name": "nginx1",
  "compressed_size_bytes": 73400320,
  "compression": {
    "enabled": true,
    "algorithm": "zstd",
    "level": 1
  },
  "compression_error": "write compressed stream: no space left on device",
  "compression_state": "compressed",
  "name": "baseline-standby",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "uncompressed_size_bytes": 4294967296
}
Returns Examples
{
  "id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "created_at": "2026-03-06T13:56:11Z",
  "kind": "Standby",
  "size_bytes": 104857600,
  "source_hypervisor": "cloud-hypervisor",
  "source_instance_id": "qilviffnqzck2jrim1x6s2b1",
  "source_instance_name": "nginx1",
  "compressed_size_bytes": 73400320,
  "compression": {
    "enabled": true,
    "algorithm": "zstd",
    "level": 1
  },
  "compression_error": "write compressed stream: no space left on device",
  "compression_state": "compressed",
  "name": "baseline-standby",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "uncompressed_size_bytes": 4294967296
}