Skip to content
Nirvana Labs Docs
Directory SDKs APISign In

Field Reference

This page lists the exact field names, types, and allowed values for VM resources, so a request can be built without trial and error. Everything here is taken from the OpenAPI specification.

The Terraform provider’s nirvana_compute_vm attribute names are identical to the JSON field names below. The Go and TypeScript SDKs use the same fields in their language’s naming convention.

Create a VM

Section titled “Create a VM”

POST /v1/compute/vms

Field Type Required Allowed values / limits
boot_volume object Yes See Boot volume
instance_type string Yes An instance type name, e.g. n1-standard-8. See Instance Types
name string Yes e.g. my-vm
os_image_name string Yes An OS image name, e.g. ubuntu-noble-2026-05-18
project_id string Yes Project UUID
public_ip_enabled boolean Yes true or false
region string Yes us-sva-2
ssh_key object Yes See SSH key
subnet_id string Yes Subnet UUID
data_volumes array of objects No See Data volumes
tags array of strings No Maximum 50 entries

os_image_name values embed a date and change as new images are published. Rather than hardcoding one, list the current names first:

Terminal window
curl -sS "https://api.nirvanalabs.io/v1/compute/vms/os_images?sort=position:asc" \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

Boot volume

Section titled “Boot volume”

boot_volume — required.

Field Type Required Allowed values / limits
size integer Yes Size in GB
type string Yes nvme or abs
tags array of strings No Maximum 50 entries

Data volumes

Section titled “Data volumes”

data_volumes — optional array. Each entry:

Field Type Required Allowed values / limits
name string Yes e.g. my-data-volume
size integer Yes Size in GB
type string Yes nvme or abs
tags array of strings No Maximum 50 entries

SSH key

Section titled “SSH key”

ssh_key — required.

Field Type Required Allowed values / limits
public_key string Yes A public key string, e.g. ssh-ed25519 AAAAC3Nza...

Example request

Section titled “Example request”
Terminal window
curl -sS https://api.nirvanalabs.io/v1/compute/vms \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
  -d '{
        "boot_volume": { "size": 100, "type": "abs" },
        "instance_type": "n1-standard-8",
        "name": "my-vm",
        "os_image_name": "ubuntu-noble-2026-05-18",
        "project_id": "123e4567-e89b-12d3-a456-426614174000",
        "public_ip_enabled": true,
        "region": "us-sva-2",
        "ssh_key": {
          "public_key": "ssh-ed25519 AAAAC3Nza... [email protected]"
        },
        "subnet_id": "123e4567-e89b-12d3-a456-426614174000",
        "tags": ["production"]
      }'

Update a VM

Section titled “Update a VM”

PATCH /v1/compute/vms/{vm_id}

Every field is optional; send only what you are changing.

Field Type Allowed values / limits
instance_type string An instance type name
name string New name
public_ip_enabled boolean true or false
tags array of strings Maximum 50 entries. Replaces the existing list

region, subnet_id, os_image_name, ssh_key, and the volume fields are not updatable through this endpoint.

VM Response Fields

Section titled “VM Response Fields”

Returned by GET /v1/compute/vms/{vm_id} and in GET /v1/compute/vms items. All of these are always present; the nullable ones may be null.

Field Type Notes
id string VM UUID
name string
project_id string
region string us-sva-2
status string See Status values
instance_type string or null
cpu_config object { "vcpu": integer }, 1–192
memory_config object { "size": integer } in GB, 1–768
boot_volume_id string
data_volume_ids array of strings
subnet_id string
vpc_id string
vpc_name string
private_ip string or null e.g. 10.0.0.1
public_ip string or null null when public_ip_enabled is false, and until an enabled IP is assigned
public_ip_enabled boolean
tags array of strings
created_at string RFC 3339 timestamp
updated_at string RFC 3339 timestamp

List VMs

Section titled “List VMs”

GET /v1/compute/vms

Parameter Type Required Allowed values / default
project_id string Yes Project UUID
limit integer No 10–100, default 10
cursor string No Cursor from a previous response. Only valid for the same filters and sort order
status string No pending, creating, updating, ready, deleting, error
region string No us-sva-2
tags array No Repeat the parameter to require several tags; a VM must carry all of them
name string No Case-insensitive substring match
public_ip_enabled boolean No
vpc_id string No
subnet_id string No
sort string No Comma-separated field:asc/field:desc in precedence order. Fields: created_at, updated_at, name, status, vcpu, memory. Default created_at:desc

project_id is a required query parameter — a request without it fails with 400, it does not fall back to a default project.

Status Values

Section titled “Status Values”

status on a VM is one of:

pending, creating, updating, ready, deleting, deleted, error

The status list filter accepts all of these except deleted.

Writes Return an Operation

Section titled “Writes Return an Operation”

Create, update, delete, and restart return 202 Accepted with an Operation — not the VM. The VM does not exist in its final form yet.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "kind": "vm",
  "type": "create",
  "status": "pending",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "resource_id": "123e4567-e89b-12d3-a456-426614174000",
  "details": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}
Field Type Notes
id string Operation UUID. Poll GET /v1/operations/{operation_id} with this
resource_id string UUID of the VM being acted on
kind string vm, volume, vpc, firewall_rule, nks_cluster, nks_node_pool
type string create, update, delete, restart
status string pending, running, done, failed, unknown
details object or null Structured description of what is changing

Poll the operation until status is done or failed, then read the VM by resource_id.

Error Responses

Section titled “Error Responses”

Create returns 400, 403, 404, 409, or 500. All errors share one shape:

{
  "type": "VALIDATION_ERROR",
  "message": "invalid id format",
  "context": { "parameters": {} },
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2025-01-01T00:00:00Z"
}
Field Type Notes
type string Machine-readable error category, e.g. VALIDATION_ERROR
message string Human-readable description
context.parameters object Which parameters were at fault, when applicable
request_id string Quote this when contacting support
timestamp string RFC 3339 timestamp
Section titled “Related”