Create a cloud VM
Creates a cloud VM. Returns an operation you can poll for status. Asynchronous: the response carries operation_id; poll GET /compute/operations/{operation_id} until status is succeeded, failed, cancelled or timed_out. If you received an operation_id, poll its status. If the create response was lost, repeat the identical request body with the original X-Idempotency-Key to recover the same operation. Keep the same body and key while the outcome is uncertain; a new key starts a separate create. Requires scope: vm.write.
Authentication
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
Query parameters
The positive numeric workspace ID to scope this request to. Zero, negative, and non-numeric values are rejected.
Request
Placement site ID from GET /compute/sites. Required: the API refuses a create without it (400 invalid_site_id). Use the same value when filtering plans and images.
Operating system distribution (e.g. ubuntu, centos, debian, rocky, windows).
Copy the selected plan’s billing_catalog, choose one supported HOURLY or MONTHLY entry from its billing_options, and merge that complete entry into the copy. Send the result here, including the canonical price_currency. Hourly requests also require an explicit selected term. Do not invent prices, drop commitment fields from the selected option, or send only billing_interval and committed. Admission validates the selection against the server’s current catalog. Amounts remain server-authoritative.
Inline public SSH keys to install on the VM, in addition to the keys referenced by ssh_key_ids.
VPC to launch the VM into. Send it together with subnet_id; one without the other is refused. Omit both to launch on the public provider network.
Subnet of vpc_id for the VM’s VPC NIC. Send it together with vpc_id.
How the VM reaches the internet. With a VPC it defaults to private. Without a VPC it is accepted only as public_ip together with reserved_public_ip_id, which attaches that Reserved IP on the public provider network. public_ip is refused on a nat_gateway VPC, and on a private VPC it needs reserved_public_ip_id.
With a VPC, primary makes the VPC NIC the VM’s only NIC. secondary keeps the public provider NIC as primary and adds the VPC as a second NIC; it needs vpc_id and subnet_id and cannot be combined with reserved_public_ip_id.
Reserved IP to attach at launch. Needs network_connectivity: public_ip and the primary attachment mode. Accepted with a VPC or, without one, on the public provider network.
Response
Always accepted.
When the operation was accepted (ISO 8601).
