Reference

API Documentation

Host Agent REST API — provision and manage virtual machines directly through the xsubi HTTP API.

Quick Start

Base URL
https://api.xsubi.com/v1
Authentication
X-API-Key: <your-key>
Content Type
application/json
Example Request curl
curl -H "X-API-Key: your-key" https://api.xsubi.com/v1/vms

Virtual Machines

/vms
Method Endpoint Description
GET /vms List all VMs
GET /vms/{id} Get VM details
POST /vms Create VM
PUT /vms/{id}/start Start VM
PUT /vms/{id}/stop Stop VM
PUT /vms/{id}/restart Restart VM
DELETE /vms/{id} Delete VM

Create VM

POST /vms

Provisions a new virtual machine on the selected hypervisor. Returns immediately with status creating — poll /vms/{id} for state transitions.

Request Body JSON
{
  "name": "web-server-01",
  "os": "ubuntu-22.04",
  "cpu": 4,
  "ram_gb": 8,
  "disk_gb": 100,
  "network": "default"
}
Response — 201 Created JSON
{
  "id": "vm-a3f8b2c1",
  "name": "web-server-01",
  "status": "creating",
  "hypervisor": "kvm",
  "ip": null,
  "created_at": "2026-03-25T10:30:00Z"
}
201 VM created, provisioning in progress
400 Invalid request body — missing or invalid fields
409 VM with that name already exists
503 Hypervisor unavailable

Get VM

GET /vms/{id}

Returns current state and metadata for a single VM.

Response — 200 OK JSON
{
  "id": "vm-a3f8b2c1",
  "name": "web-server-01",
  "status": "running",
  "hypervisor": "kvm",
  "os": "ubuntu-22.04",
  "cpu": 4,
  "ram_gb": 8,
  "disk_gb": 100,
  "ip": "10.0.1.42",
  "host": "paradise.xsubi.com",
  "created_at": "2026-03-25T10:30:00Z",
  "started_at": "2026-03-25T10:31:15Z"
}
200 VM found
404 VM not found

VM Status Values

Status Description
creating Provisioning in progress — hypervisor allocating resources
running VM is powered on and reachable
stopped VM is powered off — disk persisted
stopping Graceful shutdown in progress
starting Power-on sequence in progress
restarting Reboot in progress
error Hypervisor reported a fault — check host logs
deleted VM destroyed and disk removed

System

Host Agent
Method Endpoint Description
GET /health Health check — returns 200 when agent is up
GET /status Host status — CPU, memory, disk, VM count
GET /metrics Prometheus metrics endpoint (plain text)
GET /status — Response JSON
{
  "host": "paradise.xsubi.com",
  "hypervisor": "kvm",
  "version": "1.4.0",
  "cpu_cores": 32,
  "cpu_usage_pct": 14.3,
  "ram_total_gb": 192,
  "ram_used_gb": 87.4,
  "disk_total_gb": 4000,
  "disk_used_gb": 1240,
  "vm_count": 11,
  "vm_running": 9,
  "uptime_seconds": 1843200
}

Authentication

API Key

Current — Development

Pass your API key in the X-API-Key header on every request. Keys are scoped per customer and managed through the portal.

X-API-Key: xsk_live_a3b8f2c1...

mTLS

Planned — Production

Mutual TLS for production agent communication. Portal-to-agent traffic uses client certificates — no API keys transmitted over the wire.

OAuth 2.0

Planned — Portal SSO

OAuth 2.0 token exchange for portal-to-agent communication. Aligns with the xsubi SSO flow (Google / GitHub).

Rate Limiting

100 requests / minute
429 Too Many Requests

Rate limits are applied per API key. When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

Rate Limit Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743000060
Retry-After: 42

Error Responses

All errors return a consistent JSON envelope with error and message fields.

Error Response JSON
{
  "error": "not_found",
  "message": "VM 'vm-xyz' does not exist on this host",
  "request_id": "req-7f3a2b91"
}
Code Meaning
200 Success
201 Created
400 Bad Request — invalid or missing fields
401 Unauthorized — missing or invalid API key
403 Forbidden — key lacks permission for this resource
404 Not Found
409 Conflict — resource already exists
429 Too Many Requests — rate limit exceeded
500 Internal Server Error
503 Service Unavailable — hypervisor unreachable