Network API
POST /api/v1/network/{host_id}/{node}/apply
Section titled “POST /api/v1/network/{host_id}/{node}/apply”Apply Network
Promote the staged config. Typed confirmation required.
Doc 08 §1’s typed-name guardrail, reused verbatim from selfguard’s
self_target shape so the frontend has one confirm dialog, not two. The
phrase is the NODE NAME because the node is what is at risk: ifreload -a
with a broken bridge takes the node off the network until someone reaches
its physical console. Unlike a stopped CT this has no in-band undo.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host_id | path | integer | yes | |
node | path | string | yes |
Request body (required), application/json, ApplyIn
| Field | Type | Required | Description |
|---|---|---|---|
confirm | string | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 202 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/network/{host_id}/{node}/revert
Section titled “POST /api/v1/network/{host_id}/{node}/revert”Revert Network
Discard /etc/network/interfaces.new. No confirmation and no job: this deletes a staged file and cannot disturb the running config.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host_id | path | integer | yes | |
node | path | string | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/network/bridges
Section titled “GET /api/v1/network/bridges”List Bridges
Bridges/bonds/VLANs/physical NICs per node + the guest attachment map.
# ponytail: the attachment map costs one guest_config read per adopted app # and VM on the host: fine for a homelab, linear in guest count for a # 200-guest fleet. This is a human-triggered route, explicitly outside the # poller’s O(nodes) budget (proxmox.py’s “per-guest, user-triggered calls” # section). If it ever gets slow, cache netN in the poller’s cluster_resources # pass; do not add per-guest calls to the poll loop to get it.
One bad host (unreachable, or missing its API token credential; a
routine state, not an outage) must not 500 the whole page: it is degraded
out into errors and every other host is still served.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host | query | integer | null | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
POST /api/v1/network/bridges
Section titled “POST /api/v1/network/bridges”Create Bridge
Request body (required), application/json, BridgeIn
| Field | Type | Required | Description |
|---|---|---|---|
config | object | no | |
host_id | integer | yes | |
iface | string | yes | |
node | string | yes | |
type | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
DELETE /api/v1/network/bridges/{host_id}/{node}/{iface}
Section titled “DELETE /api/v1/network/bridges/{host_id}/{node}/{iface}”Delete Bridge
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host_id | path | integer | yes | |
node | path | string | yes | |
iface | path | string | yes |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
PUT /api/v1/network/bridges/{host_id}/{node}/{iface}
Section titled “PUT /api/v1/network/bridges/{host_id}/{node}/{iface}”Update Bridge
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
host_id | path | integer | yes | |
node | path | string | yes | |
iface | path | string | yes |
Request body (required), application/json, BridgePatchIn
| Field | Type | Required | Description |
|---|---|---|---|
config | object | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |
GET /api/v1/network/throughput
Section titled “GET /api/v1/network/throughput”Throughput
Per-host in/out series from the MetricsStore rows the poller already writes.
Same reader as /metrics/query (services/metrics.py::query_series); this endpoint only exists so the Network page can ask for both metrics across every host in one round trip instead of 2N.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
hours | query | integer | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |