Sign in

v4

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-05-09283767.7 KB
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.

envVarsEnvVars

Environment variable string→string map injected into the VM at boot. Keys must be 1–256 bytes and match shell-variable name ([A-Za-z_][A-Za-z0-9_]*); values may not contain newline, carriage return, or null bytes. Total JSON encoding ≤65536 bytes.

Response

VM is already running. The response is a VM object, and on snapshot restores it may include an optional snapshotRestoreWarnings field if pre-registered services from the snapshot failed to land on the new VM (the VM itself is good; the user can re-register the listed services manually).

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.

envVarsEnvVars

Environment variable string→string map injected into the VM at boot. Keys must be 1–256 bytes and match shell-variable name ([A-Za-z_][A-Za-z0-9_]*); values may not contain newline, carriage return, or null bytes. Total JSON encoding ≤65536 bytes.

publicIpv6string
cpuinteger required
memoryMiBinteger required
diskGiBinteger required
statusstring required

Lifecycle status. Known values: provisioning, running, stopped, pausing, paused, resuming, deleting, error. Terminal failure statuses are error and stopped; transitional values (provisioning, pausing, resuming, deleting) indicate the VM is in flight. 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
expiresAtMsinteger

Absolute timestamp in ms when the TTL fires. Set only while the VM is running (the countdown freezes on pause).

ttlRemainingMsinteger

Remaining cycle budget in ms. Set only while the VM is paused; restored to expiresAtMs on resume.

pausedAtstring date-time nullable

When the VM became paused; null otherwise.