​
Droplets API

Droplets are virtual machines powered by KubeVirt. Use these endpoints to create, manage, resize, and monitor VMs.

​
List Droplets

​
project_id
string
Filter by project ID
GET /api/v1/droplets
Response: 
[
  {
    "id": "dpl_a1b2c3d4",
    "project_id": "proj_default",
    "name": "web-server-01",
    "image": "ubuntu-22-04",
    "plan_id": "s-2vcpu-2gb",
    "status": "running",
    "public_ip": "10.0.1.15",
    "private_ip": "10.42.0.50",
    "region": "nyc1",
    "tags": ["web", "production"],
    "created_at": "2024-01-15T10:30:00Z"
  }
]

​
Create a Droplet

POST /api/v1/droplets
Request Body:
​
name
string
required
Name for the Droplet
​
image
string
required
OS image slug (e.g., ubuntu-22-04)
​
plan_id
string
required
Instance size plan (e.g., s-1vcpu-1gb)
​
region
string
required
Deployment region (e.g., nyc1)
​
ssh_key_ids
string[]
SSH key IDs to inject
​
tags
string[]
Tags for organization
​
volume_ids
string[]
Volume IDs to attach
{
  "name": "web-server-01",
  "image": "ubuntu-22-04",
  "plan_id": "s-2vcpu-2gb",
  "region": "nyc1",
  "ssh_key_ids": ["sk_abc123"],
  "tags": ["web", "production"]
}
Response: 201 Created 
{
  "id": "dpl_a1b2c3d4",
  "name": "web-server-01",
  "status": "provisioning",
  "image": "ubuntu-22-04",
  "plan_id": "s-2vcpu-2gb",
  "region": "nyc1",
  "created_at": "2024-01-15T10:30:00Z"
}

​
Get a Droplet

GET /api/v1/droplets/{id}
Returns the full Droplet object including IP addresses, attached volumes, and current status.

​
Update a Droplet (Resize)

PATCH /api/v1/droplets/{id}

{
  "plan_id": "s-4vcpu-8gb"
}

​
Delete a Droplet

DELETE /api/v1/droplets/{id}
Permanently destroys the Droplet and its associated KubeVirt VirtualMachine. Attached volumes are detached but not deleted.

​
Droplet Actions

Perform power management actions on a Droplet: 
POST /api/v1/droplets/{id}/actions
​
type
string
required
Action type: reboot, power_off, or power_on
{ "type": "reboot" }
ActionDescription
rebootGraceful restart of the VM
power_offShut down the VM
power_onStart a powered-off VM

​
VNC Console

Open a VNC console session for direct VM access: 
POST /api/v1/droplets/{id}/console
Returns a WebSocket URL for VNC connection.

​
Metrics

Get CPU, memory, and disk metrics for a Droplet: 
GET /api/v1/droplets/{id}/metrics
Response: 
{
  "cpu_usage_percent": 23.5,
  "memory_usage_bytes": 536870912,
  "memory_total_bytes": 2147483648,
  "disk_read_bytes": 1048576,
  "disk_write_bytes": 2097152
}

​
Events

List Kubernetes events for a Droplet: 
GET /api/v1/droplets/{id}/events