v33

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-175267122.5 KB

Create a snapshot for an instance

post/instances/{id}/snapshots

Path parameters

idstring required

Source instance ID or name

Request body

kind'Standby' | 'Stopped' required

Snapshot capture kind

namestring

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

tagsTags

User-defined key-value tags.

Example request

{
  "kind": "Standby",
  "name": "pre-upgrade",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "compression": {
    "enabled": true,
    "algorithm": "zstd",
    "level": 1
  }
}

Response

Snapshot created

idstring required

Auto-generated unique snapshot identifier

namestring nullable

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

kind'Standby' | 'Stopped' required

Snapshot capture kind

tagsTags

User-defined key-value tags.

source_instance_idstring required

Source instance ID at snapshot creation time

source_instance_namestring required

Source instance name at snapshot creation time

source_hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz' required

Source instance hypervisor at snapshot creation time

created_atstring date-time required

Snapshot creation timestamp

size_bytesinteger required

Total payload size in bytes

compression_state'none' | 'compressing' | 'compressed' | 'error'

Compression status of the snapshot payload memory file

compression_errorstring nullable

Compression error message when compression_state is error

compressed_size_bytesinteger nullable

Compressed memory payload size in bytes

uncompressed_size_bytesinteger nullable

Uncompressed memory payload size in bytes

Example response

{
  "id": "q7z1w7l2af4l8y7q1h7g2m3s",
  "name": "baseline-standby",
  "kind": "Standby",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "source_instance_id": "qilviffnqzck2jrim1x6s2b1",
  "source_instance_name": "nginx1",
  "source_hypervisor": "cloud-hypervisor",
  "created_at": "2026-03-06T13:56:11Z",
  "size_bytes": 104857600,
  "compression_state": "compressed",
  "compression_error": "write compressed stream: no space left on device",
  "compression": {
    "enabled": true,
    "algorithm": "zstd",
    "level": 1
  },
  "compressed_size_bytes": 73400320,
  "uncompressed_size_bytes": 4294967296
}