Management API

QuantaVirt exposes a dual-protocol management API — REST (HTTP/JSON) and gRPC (Protobuf) — for programmatic control of VMs, storage, networks, and PQC operations. Both protocols offer the same functionality; choose REST for simplicity or gRPC for high-performance automation.

API Overview #

REST API #

All REST endpoints are prefixed with /api/v1. Requests and responses use JSON. Standard HTTP methods apply: GET (read), POST (create/action), PUT (replace), PATCH (partial update), DELETE (remove).

# Base URL
http://127.0.0.1:9400/api/v1

# Common headers
Content-Type: application/json
Authorization: Bearer <token>

VM Endpoints #

Example: Create and Start a VM

# Create VM
curl -X POST http://127.0.0.1:9400/api/v1/vms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01",
    "cpu": { "count": 2 },
    "memory": { "size": "2G" },
    "devices": {
      "storage": [{ "type": "virtio-blk", "path": "web-server", "format": "qcow2" }],
      "network": [{ "type": "virtio-net", "network": "default" }]
    }
  }'
# {"name":"web-01","state":"CREATED","uuid":"a1b2c3d4-..."}

# Start VM
curl -X POST http://127.0.0.1:9400/api/v1/vms/web-01/start
# {"name":"web-01","state":"RUNNING"}

# Get VM stats
curl http://127.0.0.1:9400/api/v1/vms/web-01/stats
# {"cpu_percent":12.5,"memory_used":"512M","disk_read_iops":342,...}

Storage Endpoints #

Network Endpoints #

PQC Endpoints #

System Endpoints #

gRPC API #

The gRPC API uses Protocol Buffers for serialization and HTTP/2 for transport. It provides the same functionality as the REST API but with higher throughput, streaming support, and strongly-typed client generation.

// Proto definition (quantavirt.proto)
syntax = "proto3";
package quantavirt.v1;

service VmService {
  rpc ListVms(ListVmsRequest) returns (ListVmsResponse);
  rpc CreateVm(CreateVmRequest) returns (VmInfo);
  rpc GetVm(GetVmRequest) returns (VmInfo);
  rpc StartVm(VmActionRequest) returns (VmInfo);
  rpc StopVm(StopVmRequest) returns (VmInfo);
  rpc PauseVm(VmActionRequest) returns (VmInfo);
  rpc ResumeVm(VmActionRequest) returns (VmInfo);
  rpc MigrateVm(MigrateRequest) returns (stream MigrateProgress);
  rpc WatchVmEvents(WatchRequest) returns (stream VmEvent);
}

service PqcService {
  rpc GetStatus(Empty) returns (PqcStatus);
  rpc GenerateKey(KeyGenRequest) returns (KeyInfo);
  rpc Attest(AttestRequest) returns (AttestReport);
}

Event Streams #

Both REST (Server-Sent Events) and gRPC (streaming RPC) support real-time event notifications for VM state changes, migration progress, and security events.

# REST: Server-Sent Events
curl -N http://127.0.0.1:9400/api/v1/events

# event: vm.state_changed
# data: {"vm":"web-01","from":"STOPPED","to":"RUNNING","timestamp":"2026-01-15T10:00:00Z"}

# event: migration.progress
# data: {"vm":"db-01","progress":0.45,"transferred":"12 GiB","remaining":"15 GiB"}

# event: pqc.key_rotated
# data: {"key":"storage-master","algorithm":"ML-KEM-768","timestamp":"..."}

Authentication #

# Generate an API token
quantavirt system token-create --name automation --scopes "vm:read,vm:write,storage:read"
# Token: qvt_a1b2c3d4e5f6...

# Use token in requests
curl -H "Authorization: Bearer qvt_a1b2c3d4e5f6..." \
  http://127.0.0.1:9400/api/v1/vms

# Unix socket access uses filesystem permissions (no token required for root)

Error Handling #

// Error response format
{
  "error": {
    "code": "VM_NOT_FOUND",
    "message": "VM 'web-99' does not exist",
    "details": {}
  }
}

// HTTP status codes
// 200 — Success
// 201 — Created
// 400 — Bad request (validation error)
// 401 — Unauthorized (missing/invalid token)
// 403 — Forbidden (insufficient scope)
// 404 — Not found
// 409 — Conflict (e.g. VM already running)
// 500 — Internal server error

Client SDKs #