Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › API › Virtualization

Virtualization

API: virtualization inventory

SharedStatus: SUPPORTED when the Manager virtualization service is initializedAudience: virtualization operator, API engineer

Admin: AdminAuth() + RoleAuth("admin"). Source: virtualization_handler.go.

Service nil → 503 {"success":false,"error":"Virtualization service not initialized"}.

Agent ingest POST /api/v1/virtualization/vm-data is Agent-facing (Agent JWT + CapabilityVirtualization).

GET /api/v1/virtualization/vms

Purpose. List discovered VMs (libvirt inventory as stored by Agents).

Authentication. Admin.

Parameters (query), from ListVMs:

Scroll sideways to see the full table. Use the arrow keys when focused.

ParamMeaning
agent_idinteger Agent id
stateVM state string filter (single value placed in filter.State)
namename match (NameMatch)

Request. Empty.

Example request.

curl -sS 'https://manager.example.com:8443/api/v1/virtualization/vms?agent_id=1&state=running' \
  -H "Authorization: Bearer TOKEN"

Response (200).

{
  "success": true,
  "data": {
    "vms": [],
    "total": 0,
    "by_state": {}
  }
}

VMListResponse: vms ([]VMWithAgent), total, by_state map. Nested VM fields include id, name, state, interfaces, memory, vcpus, timestamps, plus Agent join fields. API_SCHEMA_DOCUMENTATION_BLOCKED for extra join columns that are not a second public DTO.

Errors. 400 Invalid agent_id parameter; 500 Failed to retrieve VMs; 503 service missing.

Edition. SHARED.

GET /api/v1/virtualization/vms/:vm_id

Purpose. One VM.

Authentication. Admin.

Parameters. :vm_id opaque string (libvirt id), required.

Response (200). {"success":true,"data":{"vm":{...}}} (VMDetailResponse; rule_count omitempty). 400 VM ID is required; 404 VM not found.

Edition. SHARED.

GET /api/v1/virtualization/vms/:vm_id/rules

Purpose. Rules associated with a VM.

Authentication. Admin.

Response (200). {"success":true,"data":{"vm_id":"...","rules":[],"total":0}}. rules type is service-owned. API_SCHEMA_DOCUMENTATION_BLOCKED for each rule element (gin.H data map). 404 VM not found or rules unavailable.

Edition. SHARED.

GET /api/v1/virtualization/vms/:vm_id/interfaces

Purpose. Interfaces for one VM.

Authentication. Admin.

Response (200). {"success":true,"data":{"vm_id":"...","interfaces":[],"total":N}}. Interface objects follow VirtualizationInterfaceInfo (name, type, mac, bridge, model, ips, stats, rates, vm_name, vm_id). 404 VM not found or no interfaces available.

Edition. SHARED.

GET /api/v1/virtualization/interfaces

Purpose. All virtual interfaces across Agents.

Authentication. Admin.

Parameters. None.

Response (200). {"success":true,"data":{"interfaces":[],"total":N}} (InterfaceListResponse). 500 Failed to retrieve interfaces.

Edition. SHARED.

GET /api/v1/virtualization/interfaces/:name

Purpose. One interface by name.

Authentication. Admin.

Parameters. :name.

Response. success + interface detail or 404. API_SCHEMA_DOCUMENTATION_BLOCKED for extra gin.H wrapping in GetInterface beyond the envelope.

Edition. SHARED.

GET /api/v1/virtualization/interfaces/:name/stats

Purpose. Interface counters and rates (InterfaceStatsResponse: interface, vm_id, vm_name, stats, rates).

Authentication. Admin.

Edition. SHARED.

GET /api/v1/virtualization/interfaces/:name/traffic/history

GET /api/v1/virtualization/interfaces/:name/traffic/summary

GET /api/v1/virtualization/interfaces/:name/traffic/timeseries

GET /api/v1/virtualization/traffic/summary

Purpose. Historical/summary/timeseries traffic for virtual interfaces.

Authentication. Admin.

Response. success/data envelopes. API_SCHEMA_DOCUMENTATION_BLOCKED — these handlers assemble gin.H from metrics queries without a single exported DTO covering every bucket field.

Edition. SHARED.

Security. No published PPS product metric.

POST /api/v1/virtualization/discovery

Purpose. Trigger VM discovery.

Authentication. Admin.

Request. Optional DiscoveryRequest (handler-local). Empty body is typically accepted if bind allows zero values.

Response. success/error. API_SCHEMA_DOCUMENTATION_BLOCKED for discovery result map.

Edition. SHARED.

GET /api/v1/virtualization/summary

GET /api/v1/virtualization/cache-stats

GET /api/v1/virtualization/available-workloads

POST /api/v1/virtualization/reload-cache

Purpose. Summary widget, cache stats, normalized workloads (AvailableWorkloadsResponse), cache reload.

Authentication. Admin.

Response. V1-like success/data. Workloads: workloads, total. Cache/summary maps: API_SCHEMA_DOCUMENTATION_BLOCKED.

Edition. SHARED.

POST /api/v1/virtualization/vm-data

Purpose. Agent ingest of VM inventory (UpdateVMData).

Authentication. Agent JWT + capability CapabilityVirtualization (+ Enterprise mTLS wrapper).

Audience. Agent-facing — not a browser cookbook.

Request. Heartbeat-shaped VM arrays converted via virtualization_contracts.go. API_SCHEMA_DOCUMENTATION_BLOCKED for the exact bind struct if the handler uses []map / service types rather than RegisterRequest. Known conversion fields: VM id, name, state, interfaces (name, type, mac, bridge, model, ips, stats, rates).

Edition. SHARED implementation; Agent-facing publication.

Security. Agent token must match capability. Not a browser API.

Isolation

Network isolation CRUD lives under /api/v1/isolation/*. Detailed isolation API books are provided separately to Enterprise customers.