Skip to navigation
API ReferenceCloud VMs

Create a cloud VM

Creates a cloud VM. Returns an operation you can poll for status. Requires scope: vm.write.

Authentication

AuthorizationBearer

IBEE platform API token. Production tokens start with ibee_prod_key_; development tokens start with ibee_dev_key_. Use a token only with its matching gateway environment.

Headers

X-Idempotency-KeystringRequired
Unique key used to safely retry write operations.

Query parameters

workspace_idstringRequiredformat: "^[1-9][0-9]*$">=1 character

The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected.

Request

This endpoint expects an object.
namestringRequired>=1 character
Display name for the virtual machine.
os_distrostringRequired

Operating system distribution (e.g. ubuntu, centos, debian, rocky, windows).

os_typeenumRequired
Operating system family.
Allowed values:
template_idstringRequired
OS template or image ID returned by the compute catalog.
cpuintegerRequired>=1
Number of vCPUs.
ram_mbintegerRequired>=512
RAM in megabytes.
plan_idstringRequired
Billable compute plan ID returned by the compute catalog.
billing_catalogmap from strings to anyRequired

The selected plan's billing_catalog object from GET /compute/plans, passed through unmodified — the same flow the portal uses. Treat it as opaque. Billing charges are always computed server-side from plan_id, not from this echoed copy.

site_idstring or nullOptional>=1 character

Optional placement site ID. Omit for automatic placement. To pin the VM, copy site_id from GET /compute/sites and use the same value when filtering plans and images.

disk_gbinteger or nullOptional>=10
Root disk size in gigabytes.
ssh_key_idslist of stringsOptional
SSH key IDs to inject into the VM.
tagslist of stringsOptional
Arbitrary tags for filtering and organization.

Response

VM creation accepted.
operation_idstring
vm_idstring
statusstring
submitted_atdatetime

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error