Create a snapshot for an instance

client.Instances.Snapshots.New(ctx, id, body) (*Snapshot, error)

post/instances/{id}/snapshots

ParametersExpand Collapse

id string

body InstanceSnapshotNewParams

Kind param.Field[SnapshotKind]

Snapshot capture kind

Compression param.Field[SnapshotCompressionConfig]optional

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

Name param.Field[string]optional

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

maxLength63

Tags param.Field[map[string, string]]optional

User-defined key-value tags.

ReturnsExpand Collapse

type Snapshot struct{…}

ID string

Auto-generated unique snapshot identifier

CreatedAt Time

Snapshot creation timestamp

formatdate-time

Kind SnapshotKind

Snapshot capture kind

Accepts one of the following:

const SnapshotKindStandby SnapshotKind = "Standby"

const SnapshotKindStopped SnapshotKind = "Stopped"

SizeBytes int64

Total payload size in bytes

formatint64

SourceHypervisor SnapshotSourceHypervisor

Source instance hypervisor at snapshot creation time

Accepts one of the following:

const SnapshotSourceHypervisorCloudHypervisor SnapshotSourceHypervisor = "cloud-hypervisor"

const SnapshotSourceHypervisorFirecracker SnapshotSourceHypervisor = "firecracker"

const SnapshotSourceHypervisorQemu SnapshotSourceHypervisor = "qemu"

const SnapshotSourceHypervisorVz SnapshotSourceHypervisor = "vz"

SourceInstanceID string

Source instance ID at snapshot creation time

SourceInstanceName string

Source instance name at snapshot creation time

CompressedSizeBytes int64optional

Compressed memory payload size in bytes

formatint64

Compression SnapshotCompressionConfigoptional

Enabled bool

Enable snapshot memory compression

Algorithm SnapshotCompressionConfigAlgorithmoptional

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

Accepts one of the following:

const SnapshotCompressionConfigAlgorithmZstd SnapshotCompressionConfigAlgorithm = "zstd"

const SnapshotCompressionConfigAlgorithmLz4 SnapshotCompressionConfigAlgorithm = "lz4"

Level int64optional

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

CompressionError stringoptional

Compression error message when compression_state is error

CompressionState SnapshotCompressionStateoptional

Compression status of the snapshot payload memory file

Accepts one of the following:

const SnapshotCompressionStateNone SnapshotCompressionState = "none"

const SnapshotCompressionStateCompressing SnapshotCompressionState = "compressing"

const SnapshotCompressionStateCompressed SnapshotCompressionState = "compressed"

const SnapshotCompressionStateError SnapshotCompressionState = "error"

Name stringoptional

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

Tags map[string, string]optional

User-defined key-value tags.

UncompressedSizeBytes int64optional

Uncompressed memory payload size in bytes

formatint64

Create a snapshot for an instance

package main

import (
  "context"
  "fmt"

  "github.com/kernel/hypeman-go"
  "github.com/kernel/hypeman-go/option"
)

func main() {
  client := hypeman.NewClient(
    option.WithAPIKey("My API Key"),
  )
  snapshot, err := client.Instances.Snapshots.New(
    context.TODO(),
    "id",
    hypeman.InstanceSnapshotNewParams{
      Kind: hypeman.SnapshotKindStandby,
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", snapshot.ID)
}

{
  "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
}