GET /api/vms

List the classic VMs known to this Lite host. AppVMs are exposed by GET /api/appvm/vms, not by this collection. API-key responses redact sensitive cloud-init fields.

The response is a pagination envelope (items + page metadata), and the collection accepts query parameters for paging and filtering. Items are ordered newest-first (created_at descending, id as tiebreaker) so pages are stable.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/vms

read

List classic VMs and in-progress classic VM provisions.

Use your host URL and API key as shell variables:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

cURL template

curl --request GET "${baseUrl}/api/vms" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.
Query	page	integer	no	1-based page number. Defaults to 1; a page past the end returns an empty items.
Query	per_page	integer	no	Items per page. Defaults to 50, clamped to 1–200.
Query	state	string	no	Comma-separated states to include, e.g. running,stopped. Matches either the display state or the underlying lifecycle state, so running also returns VMs still booting.
Query	q	string	no	Case-insensitive substring match over id, discovered IPv4, and hostname.
Query	network_id	string	no	Only VMs attached to this VM network id.

Response

Returns a pagination envelope whose items are classic VmView objects. items can also include a classic VM provision while image download or creation is in progress.

Field	Type	Description
items	VmView[]	The VMs on this page (see schema below).
page	integer	Echoed 1-based page number.
per_page	integer	Effective page size after clamping.
total	integer	Total VMs matching the filters, across all pages.
total_pages	integer	Number of pages at this per_page (0 when total is 0).

Fields marked optional are omitted from the JSON object when they have no value. Fields marked nullable are always present and use null when they do not apply.

VmView

Field	Type	Presence	Description
id	string	always	VM id.
state	string	always	Stored lifecycle state: created, running, paused, stopped, or failed.
display_state	string	always	User-facing state. In addition to lifecycle states, classic VM provisioning can report booting, downloading, creating, or provision_failed.
vcpus	integer	always	Assigned vCPU count.
memory_mb	integer	always	Assigned memory in MiB.
kernel_path	string or null	nullable	PVH kernel path when direct kernel boot is used.
firmware_path	string or null	nullable	Firmware path when firmware boot is used.
disk_path	string	always	Root disk path on the Lite host. An in-progress classic provision returns an empty string until the disk exists.
volumes	array of VmVolume	always	Attached data volumes, in disk order. The item shape is documented below.
seed_disk	SeedDisk	optional	The host-generated cloud-init seed disk. Present only on a VM with cloud_init. It is not a data volume and cannot be detached, but it does occupy a guest device letter.
cmdline	string	always	Kernel command line.
console_socket_path	string	always	Host serial-console socket path. An in-progress classic provision returns an empty string.
failure_reason	FailureReason	optional	Human-readable and machine-readable failure details.
pid	integer	optional	Cloud Hypervisor process id when known.
nets	array of VmNetwork	always	Network interfaces in order: index 0 is the guest's eth0. Empty array when the VM has no interface.
platform	VmPlatform	optional	SMBIOS platform values.
disk	VmDisk	optional	Agent-managed root disk metadata.
image	VmImage	optional	Classic VM source image identity.
cloud_init	CloudInitView	optional	Classic VM cloud-init view. API-key responses omit cloud_init.password.
io_limit	DiskIoLimit	optional	Root-disk throughput ceiling. Omitted when the disk is unthrottled.
nested	boolean	optional	Whether the guest may itself run KVM. Omitted when never set explicitly, which means the hypervisor default applies.
cpu_affinity	array of integers	optional	Host logical CPUs the vCPUs are pinned to. Omitted when unpinned.
cpu_topology	CpuTopology	optional	Guest-visible CPU topology. Omitted when the hypervisor default applies.
pci_devices	array of strings	always	Passed-through host PCI devices, as full BDF strings such as 0000:07:00.0. Empty array when nothing is passed through.
balloon_mb	integer	optional	Memory reclaim target in MiB. Omitted when no memory is being reclaimed.
created_at	RFC 3339 string	optional	Creation timestamp.
discovered_ipv4	string	optional	Observed guest IPv4 address.
guest_panicked_at	RFC 3339 string	optional	When a guest kernel panic was observed over pvpanic. state stays running: the hypervisor is alive and the guest is not.
shutting_down	boolean	optional	Present as true while ACPI shutdown is pending; omitted when false.
mode	string	always	Always vm on this endpoint.

volumes[] (VmVolume)

Field	Type	Presence	Description
id	string	always	Stable per-VM volume id, such as data0.
path	string	always	Volume file path on the Lite host.
virtual_size_bytes	integer	always	Virtual size visible to the guest, in bytes.
fmt	string	always	Volume image format. Currently qcow2.
readonly	boolean	always	Whether the volume is attached read-only.
owned	boolean	always	Whether the agent owns and manages the volume file. true means deleting the VM erases it.
volume_id	string	optional	Id of the matching first-class volume, whose lifetime is independent of this VM. Omitted for a VM-owned disk.
device	string	always	Guest block device, such as /dev/vdc. Derived from disk order, so detaching an earlier disk shifts this one down a letter. Mount by UUID or label in the guest, never by device letter.
disk_bytes	integer	optional	Bytes the volume file actually occupies, which is smaller than virtual_size_bytes for a sparse image. Only the single-VM read fills this in; list responses omit it rather than pay a stat per row.

seed_disk (SeedDisk)

Field	Type	Presence	Description
device	string	always	Guest block device holding the cloud-init seed. It sits directly after the root disk, so data volumes on a cloud-init VM start one letter later than on a VM without one.
size_bytes	integer	always	Size the guest sees. Fixed, and small: the seed holds only the rendered cloud-init files.

io_limit (DiskIoLimit)

Field	Type	Presence	Description
bps_total	integer	optional	Combined read and write ceiling in bytes per second. Omitted when unlimited.
iops_total	integer	optional	Combined read and write ceiling in IO operations per second. Omitted when unlimited.

cpu_topology (CpuTopology)

Field	Type	Presence	Description
sockets	integer	always	Guest-visible socket count.
cores	integer	always	Cores per socket.
threads	integer	always	Threads per core. sockets × cores × threads always equals vcpus.

failure_reason (FailureReason)

Field	Type	Presence	Description
detected_at	RFC 3339 string	always	Time the failure was detected.
summary	string	always	One-line operator-readable explanation.
detail	object	always	Tagged machine-readable detail. kind is one of socket_gone, socket_dead, ping_timeout, process_exit, process_signal, missing_pid, disk_missing, invalid_vm_id, boot_timeout, or provision_failed.
detail.kind	string	always	Failure-detail discriminator.
detail.code	integer	conditional	Process exit code when kind is process_exit.
detail.signum	integer	conditional	Signal number when kind is process_signal.
detail.path	string	conditional	Missing disk path when kind is disk_missing.
detail.id	string	conditional	Invalid VM id when kind is invalid_vm_id.
detail.seconds	integer	conditional	Timeout duration when kind is boot_timeout.
cause	string	always	Higher-level cause: operator_shutdown, guest_shutdown, ch_crash, vmm_hang, disk_missing, boot_timeout, provision_failed, record_invalid, or unknown.

nets[] (VmNetwork)

Field	Type	Presence	Description
mode	string	always	Network mode. Currently bridge.
bridge	string	always	Host bridge interface.
tap_name	string	always	Agent-created tap interface.
mac	string	always	Guest MAC address.
network_id	string	optional	Host network id.
vlan_tag	integer	optional	802.1Q VLAN tag.
ipv4	VmNetworkIpConfig	optional	IPv4 assignment metadata.
ipv6	VmNetworkIpConfig	optional	IPv6 assignment metadata.
mtu	integer	optional	Interface MTU.
isolated	boolean	optional	Per-VM bridge port-isolation override.
spoof_guard	boolean	optional	Per-VM anti-spoof override.
rate_limit_mbps	integer	optional	Symmetric network rate limit in Mbps.
allowed_ips	array of strings	optional	Extra source addresses or CIDRs anti-spoof lets through, beyond the interface's own address. Omitted when empty.
dhcp_snooped_ipv4	string	optional	Guest IPv4 learned from the upstream DHCP ACK. Authoritative, and the preferred source for discovered_ipv4. Only set on an interface with no static ipv4.
last_observed_ipv4	string	optional	Last IPv4 seen for this MAC in the host neighbor table. Guest-asserted, so it is a display fallback only, and it survives ARP expiry.

nets[].ipv4 / nets[].ipv6 (VmNetworkIpConfig)

Field	Type	Presence	Description
address	string	always	CIDR address.
gateway	string	optional	Gateway address without a CIDR suffix.
dns_servers	array of strings	optional	DNS server addresses.

platform (VmPlatform)

Field	Type	Presence	Description
serial_number	string	optional	SMBIOS serial number.

disk (VmDisk)

Field	Type	Presence	Description
mode	string	always	Root disk mode. Currently copy.
base_path	string	always	Canonical source image path.
virtual_size_bytes	integer	always	Virtual size visible to the guest, in bytes.
owned	boolean	always	Whether the agent owns and manages the root disk file.
image_fmt	string	optional	Root disk image format. Currently qcow2.
qsd_pid	integer	optional	Storage process id.
qsd_start_time	integer	optional	Storage process start time in boot-relative clock ticks.
qsd_blk_socket	string	optional	Root-disk block socket path.
qsd_qmp_socket	string	optional	Storage control socket path.
runtime	VolumeRef	optional	Backend-independent runtime identity.

disk.runtime (VolumeRef)

Field	Type	Presence	Description
backend	string	always	Storage backend. Currently qsd.
pid	integer	always	Storage process id.
start_time	integer	always	Storage process start time in boot-relative clock ticks.
blk_socket	string	always	Root-disk block socket path.
qmp_socket	string	always	Storage control socket path.

image (VmImage)

Field	Type	Presence	Description
image_id	string	always	Source image id.
distro	string	optional	Distribution name.
version	string	optional	Distribution version.

cloud_init (CloudInitView)

Field	Type	Presence	Description
hostname	string	always	Guest hostname.
user	string	always	Guest account configured by cloud-init.
ssh_authorized_keys	array of strings	always	SSH public keys.
password	string	optional	Guest password. This field is always omitted from API-key responses.
network	CloudInitNetwork	optional	Rendered static guest network input.
instance_id	string	always	NoCloud instance identity.
console_autologin	boolean	always	Whether serial-console auto-login is enabled.
sudo	boolean	always	Whether a non-root cloud-init user receives sudo access.

cloud_init.network (CloudInitNetwork)

Field	Type	Presence	Description
ipv4	CloudInitIpConfig	always	Static IPv4 configuration.
ipv6	CloudInitIpConfig	optional	Static IPv6 configuration.

cloud_init.network.ipv4 / ipv6

Field	Type	Presence	Description
address	string	always	CIDR address.
gateway	string	optional	Gateway address without a CIDR suffix.
dns	array of strings	optional	DNS server addresses. This field is named dns, not dns_servers.

Examples

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

# First page of running VMs, 50 per page.
curl "${baseUrl}/api/vms?page=1&per_page=50&state=running" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

{
  "items": [
    {
      "id": "demo-api-vm",
      "state": "running",
      "display_state": "running",
      "vcpus": 2,
      "memory_mb": 2048,
      "kernel_path": null,
      "firmware_path": "/usr/share/virtainer/CLOUDHV.fd",
      "disk_path": "/var/lib/virtainer/vms/demo-api-vm/root.qcow2",
      "volumes": [],
      "cmdline": "",
      "console_socket_path": "/run/virtainer/demo-api-vm/console.sock",
      "nets": [
        {
          "mode": "bridge",
          "bridge": "vmbr0",
          "tap_name": "vtdemoapi0",
          "mac": "02:00:00:12:34:56",
          "network_id": "default"
        }
      ],
      "pci_devices": [],
      "image": {
        "image_id": "debian-13-x86_64",
        "distro": "debian",
        "version": "13"
      },
      "mode": "vm"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 1,
  "total_pages": 1
}

Errors

Status	Code	Description
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.