Skip to navigation
API ReferenceGPU VMs

Create a GPU VM

Creates a GPU 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).

os_typeenumRequired
Operating system family.
Allowed values:
template_idstringRequired

GPU-compatible template ID returned by the compute catalog.

cpuintegerRequired>=1
Number of vCPUs.
ram_mbintegerRequired>=512
RAM in megabytes.
gpu_countintegerRequired>=1
Number of GPUs to attach.
gpu_modelstringRequired

GPU model (e.g. A100, H100, L40S, RTX4090).

plan_idstringRequired
Billable GPU plan ID returned by the compute catalog.
billing_catalogmap from strings to anyRequired

The selected plan's billing_catalog object from GET /compute/plans?vm_type=gpu, 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