Skip to navigation

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.

# Example request with curl (set IBEE_API_TOKEN to a platform API token and WORKSPACE_ID to the workspace first).
curl -X POST "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name": "web-server-01", "plan_id": "019f25b7-c1b3-7a9e-bfb9-8c83e323b517", "site_id": "68b99bd78a8eda32ff3f16ea", "template_id": "tmpl_ubuntu_2204", "os_distro": "ubuntu", "os_type": "linux", "cpu": 2, "ram_mb": 4096, "billing_catalog": {"sku_id": "<sku_id>", "sku_code": "<sku_code>", "billing_interval": "HOURLY", "committed": false, "commitment_period": "HOURLY", "unit_price_minor": 1, "price_currency": "INR"}}'

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.
site_idstringRequired>=1 character

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.

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_catalogobjectRequired

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.

disk_gbinteger or nullOptional>=10
Root disk size in gigabytes.
ssh_key_idslist of stringsOptional
SSH key IDs to inject into the VM.
ssh_keyslist of stringsOptional

Inline public SSH keys to install on the VM, in addition to the keys referenced by ssh_key_ids.

vpc_idstring or nullOptional

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_idstring or nullOptional

Subnet of vpc_id for the VM’s VPC NIC. Send it together with vpc_id.

network_connectivityenum or nullOptional

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.

Allowed values:
vpc_attachment_modeenumOptionalDefaults to primary

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.

Allowed values:
reserved_public_ip_idstring or nullOptional

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.

tagslist of stringsOptional
Arbitrary tags for filtering and organization.

Response

VM creation accepted.
operation_idstring
ID of the queued operation.
vm_idstring
ID of the VM the operation acts on.
statusstring

Always accepted.

submitted_atdatetime

When the operation was accepted (ISO 8601).

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
413
Content Too Large Error
422
Unprocessable Entity Error
423
Locked Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error