GET /api/networks

Read host networks, observed state, and the default VM network pointer.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/networks

read

Read host networks and the current default VM network pointer.

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/networks" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.

Response

Returns a network list object.

Object	Field	Type	Presence	Description
Response	networks	array of objects	always	Host networks known to Virtainer.
	suggested_bridge	string	always	Next available PVE-style bridge name, such as vmbr1.
	default_vm_network_id	string or null	always	Explicit default network for new VMs. null means the host falls back to the bridged management network.
networks[]	id	string	always	Network id. The default management network is usually default.
	name	string	always	Display name.
	bridge	string	always	Linux bridge interface used by VM tap devices.
	role	string	always	management or vm_only.
	scope	string	always	Network scope, for example host_local.
	uplink	string or null	always	Physical uplink interface, if any.
	is_bridged	boolean	always	Whether VMs can attach to this network through a bridge.
	l3_method	string	always	dhcp, static, or none.
	policy	object	always	Network-level security policy overrides. Empty object means inherit node defaults.
	observed	object	always	Live host observation. Nested fields are documented in the networks[].observed rows below.
	vm_count	integer	always	Number of VMs attached to this network.
networks[].policy	spoof_guard	boolean	optional	Network-level default for MAC/IP anti-spoofing. Omitted means inherit the node default.
	port_isolation	boolean	optional	Network-level default for bridge port isolation. Omitted means inherit the node default.
networks[].observed	bridge_exists	boolean	always	Whether the bridge device exists on the host.
	members	array of strings	always	Current bridge members, including uplink and VM tap devices.
	has_ipv4	boolean	always	Whether the bridge currently has an IPv4 address.
	healthy	boolean	always	Aggregate readiness for VM attachment and host network health.

Examples

Call example

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

curl "${baseUrl}/api/networks" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

{
  "networks": [
    {
      "id": "default",
      "name": "Default",
      "bridge": "vmbr0",
      "role": "management",
      "scope": "host_local",
      "uplink": "eno1",
      "is_bridged": true,
      "l3_method": "dhcp",
      "policy": {},
      "observed": {
        "bridge_exists": true,
        "members": ["eno1"],
        "has_ipv4": true,
        "healthy": true
      },
      "vm_count": 2
    }
  ],
  "suggested_bridge": "vmbr1",
  "default_vm_network_id": "default"
}

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.
500	NETWORK_ERROR or INTERNAL	The host could not observe network state.