hzel Docs

PrivateNetwork

Returned by all network CRUD endpoints (POST, GET, PATCH /api/v1/networks/…).

Fields

Field	Type	Description
`id`	`string (UUID)`	Unique network identifier.
`owner_user_id`	`string (UUID)`	ID of the user who created the network.
`name`	`string`	Human-readable display label for the network.
`bridge_name`	`string`	Linux bridge device name on the Proxmox host (e.g. `"vmbr105"`).
`bridge_id`	`integer`	Numeric suffix N of `vmbrN`; stored for display and reconstruction (stored as `i32`).
`cidr`	`string`	RFC 1918 CIDR block allocated to this network (e.g. `"10.42.0.0/24"`).
`state`	`string`	Provisioning state. One of `"creating"`, `"active"`, `"deleting"`, `"failed"`.
`created_at`	`string (ISO 8601)`	UTC timestamp when the network was created.

State values

Value	Meaning
`"creating"`	Proxmox bridge is being provisioned.
`"active"`	Bridge exists and containers can be attached.
`"deleting"`	Bridge is being torn down.
`"failed"`	Provisioning or deletion could not be completed.

Example

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "owner_user_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "dev-internal",
  "bridge_name": "vmbr105",
  "bridge_id": 105,
  "cidr": "10.42.0.0/24",
  "state": "active",
  "created_at": "2025-06-15T12:00:00Z"
}

NetworkMembership

Returned by the member management endpoints and by GET /api/v1/containers/{container_id}/networks. Represents a container's NIC attachment to a private network.

Fields

Field	Type	Description
`id`	`string (UUID)`	Unique membership identifier.
`network_id`	`string (UUID)`	ID of the network this membership belongs to.
`container_id`	`string (UUID)`	ID of the attached container.
`private_ip`	`string`	Static host address allocated from the network's CIDR (e.g. `"10.42.0.3"`).
`net_index`	`integer`	Proxmox `netN` slot index (1–15) used for this NIC on the container (stored as `i16`).
`state`	`string`	Attachment state. One of `"attaching"`, `"active"`, `"detaching"`, `"failed"`.
`created_at`	`string (ISO 8601)`	UTC timestamp when the container was attached to the network.

State values

Value	Meaning
`"attaching"`	NIC is being configured on the Proxmox node.
`"active"`	Container is connected and reachable at `private_ip`.
`"detaching"`	NIC is being removed.
`"failed"`	Attach or detach operation could not be completed.

Example

{
  "id": "b2c3d4e5-0000-0000-0000-000000000002",
  "network_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "container_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "private_ip": "10.42.0.3",
  "net_index": 1,
  "state": "active",
  "created_at": "2025-06-15T12:05:00Z"
}

Network Structures