Sign in
vms

Launch a VM

Creates a new VM, either from a machineType (fresh boot) or a snapshotId (restore from snapshot).

  • Returns 201 when the VM is already running in the response.
  • Returns 202 when the VM is queued; clients must poll GET /v1/vms/{id} until status transitions to running. Terminal failure statuses are error and stopped.

The SDK's launch() helper handles the 201/202 branching and polling automatically.

post/v1/vms

Request body

namestring

User-facing name (trimmed + whitespace-collapsed, max 64 runes after normalization — longer values are truncated server-side). Auto-generated as vm-<8-char-id-prefix> if empty.

machineTypestring

Machine size identifier (e.g. c1m2, c2m4). Controls CPU and memory allocation. Must be supplied on launch unless restoring from a snapshot.

snapshotIdstring

Snapshot ID to restore from.

diskGiBinteger

Override the default disk size (GiB).

metadataMetadata

Free-form string→string map. Server-enforced limits: up to 256 keys, key length 1–256 bytes, value length ≤4096 bytes, total JSON encoding ≤65536 bytes.

Response

VM is already running

idstring required
namestring required
orgIdstring required
machineNamestring
sourceNamestring

Source snapshot or image name (empty on fresh boot).

metadataMetadata

Free-form string→string map. Server-enforced limits: up to 256 keys, key length 1–256 bytes, value length ≤4096 bytes, total JSON encoding ≤65536 bytes.

publicIpv6string
cpuinteger required
memoryMiBinteger required
diskGiBinteger required
statusstring required

Lifecycle status. Known values: provisioning, running, stopped, deleting, error. Terminal failure statuses are error and stopped; any other non-running value indicates the VM is still transitioning. Additional values may be introduced in future server versions; clients should treat unknown values as "in transition" rather than as hard errors.

createdAtstring date-time required
deletedAtstring date-time nullable

Changes