Skip to navigation
API Referencevms

Create a new virtual machine

Creates a new VM and returns it. To preview pricing without creating anything, use POST /compute/vms/cost-estimate instead.

Authentication

X-API-Client-IDstring
API Client ID
X-API-Client-Secretstring
API Client Secret

Request

This endpoint expects an object.
namestringRequiredformat: "^[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$"1-63 characters
VM name. It must be 1 to 63 characters, start with a letter, end with a letter or a digit, and hold only letters, digits and hyphens.
regionstringRequired
Region label
vmPackagestringRequired
VM package label
vmSpecsobjectRequired
VM specifications
imagestringRequired
Image label to use for the VM
subscriptionPeriodenumRequired
Subscription period
Allowed values:
networkstringOptionalformat: "uuid"

UUID of a pre-existing network to attach the VM to. Omit to have an isolated network auto-created for the VM (post-create access is then configured via networkAccess). An auto-created network is deleted with the VM once its last VM is removed; a network you supply is not.

tagslist of stringsOptional
List of tags to add to the VM
keypairslist of stringsOptional

Names of SSH key pairs to use (optional)

userdatastringOptional

Base64-encoded cloud-init userdata script (optional)

networkAccessobjectOptional

Optional network access configuration applied after the VM is created. Only honored when no network is provided (i.e. an isolated network is auto-created). Applies the requested outbound traffic setting and adds port forwarding + firewall rules for the requested inbound ports against the network’s public IP.

Response

The virtual machine has been created
idstringformat: "uuid"
Unique identifier for this virtual machine.
namestring

Human-readable name for the VM. Shown in dashboards and CLI output.

statusstring

Current lifecycle state of the VM. Observed values include CREATING, STARTING, CREATED, STARTED, STOPPING, STOPPED, and DESTROYED. Treat this as an open set — new states may be introduced over time.

regionstring

Region the VM is provisioned in. References a region label from /v1/compute/regions.

cpuinteger
Number of virtual CPUs allocated to the VM.
memoryMbinteger
Memory allocated to the VM, in megabytes.
rootDiskGbinteger
Root disk size, in gigabytes.
subscriptionPeriodstring
Billing cadence applied to this VM.
imagestring

Image label the VM was provisioned from. References /v1/compute/images.

ipAddressstringformat: "ipv4"
Primary IP address assigned to the VM on its network.
networkNamestring or null
Name of the network or VPC tier this VM is attached to. Null while the VM is still provisioning.
networkIdstring or nullformat: "uuid"
Identifier of the network or VPC tier this VM is attached to. Null while the VM is still provisioning.
rootVolumeIdstring or nullformat: "uuid"
Identifier of the VM root volume. Null while the VM is still provisioning.
createdAtdatetime
When the VM was first provisioned.
passwordMessagestring

Human-readable note explaining how the initial VM password will be delivered.

vmPackagestringOptional

Package label identifying the CPU/memory/disk preset this VM uses.

tagslist of stringsOptional
Tags assigned to this VM for grouping and filtering.
imageDisplayNamestringOptional
Friendly name of the source image.
versionStartedAtdatetimeOptional

When the current billing version started (set when the VM is scaled or its disk is resized). Only present if the VM has been modified since creation.

marketplaceAppobjectOptional

Source marketplace app, when the VM was deployed from one. Absent for OS-only deploys.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error