API Reference¶

Proxbox exposes a REST API under /api/plugins/proxbox/ for all of its persisted models. The plugin registers 29 NetBoxModelViewSet classes — one per model — via a NetBoxRouter, so every model is discoverable at the API root. The API inherits NetBox's standard DRF infrastructure — authentication, permissions, pagination, and filtering work identically to native NetBox endpoints.

Read-only endpoints

Two endpoints are intentionally read-only (GET / HEAD / OPTIONS only) to preserve the four-eyes approval workflow and intent branch safety: deletion-requests/ and apply-jobs/. Attempting a POST, PUT, PATCH, or DELETE to those paths returns HTTP 405. See Deletion Requests and Apply Jobs below and the Deletion Requests operations guide for the full safety policy.

Base URL¶

/api/plugins/proxbox/

A GET request to the root returns links to all top-level resources plus the nested /endpoints/ namespace.

Semantic MCP bridge¶

For the full consumer, operator, and agent contract—including discovery, authentication, tool schemas, executable examples, safety rules, errors, compatibility, and troubleshooting—see the dedicated Semantic MCP Bridge guide.

After an exact compatible SDK identity is activated, the API root explicitly advertises a versioned semantic-tool manifest:

{
  "mcp": {
    "schema_version": "1",
    "manifest": "/api/plugins/proxbox/mcp/"
  }
}

While the checked activation record is blocked, the root omits this member and direct GET /api/plugins/proxbox/mcp/ returns HTTP 503 with the activation record. The producer can therefore ship its schema without falsely advertising an operational consumer pair.

GET /api/plugins/proxbox/mcp/ is the reserved route for a read-only producer descriptor consumed by a future compatible netbox-sdk. No released SDK identity is currently activated; tests/fixtures/netbox_sdk_bridge_activation.json remains fail-closed. Once an exact compatible release is immutably provisioned and passes the paired CI gate, the SDK exposes these descriptors through generic plugin_list_tools and plugin_call_tool MCP tools backed by the existing sync/schedule/ DRF view:

Tool	Method and path	Effect	Existing permission boundary
`list_sync_jobs`	`GET sync/schedule/`	read	`IsAuthenticatedOrLoginNotRequired` plus `core.add_job`
`schedule_sync`	`POST sync/schedule/`	destructive	`IsAuthenticatedOrLoginNotRequired` plus `core.add_job`

The manifest's strict JSON Schemas mirror the existing schedule serializer and response envelopes. It does not execute operations, hold credentials, import FastMCP, or bypass DRF permissions. netbox-sdk performs discovery, input and output validation, path confinement, and disabled-by-default server-wide mutation gating; the target view remains authoritative for NetBox authorization and scheduling. For schedule_sync, bridge v1 accepts a unique nonempty sync_stages list of 13 concrete stages; it does not advertise the legacy REST "all" sentinel. An explicit Proxmox endpoint scope is fail-closed: if any requested endpoint ID is unknown or disabled, the request returns HTTP 400 and no job is enqueued. An explicitly present endpoint scope must contain at least one ID; omit the field to request the deliberate all-endpoints behavior. IDs are positive signed-64-bit PKs. Integer JSON literals retain that full range; integral float/Decimal forms normalize only through 9007199254740991, and larger float forms fail before ORM lookup rather than risk rounded identity. Booleans, strings, fractions, and out-of-range values also fail. netbox_endpoint_ids is not exposed because the bridge has no end-to-end semantics for it. recurrence contains exactly one bounded unit/value member, and schedule_at is strict timezone-bearing RFC 3339 with a representable normalized instant. Unknown properties, duplicate list entries, nonpositive endpoint IDs, and job names longer than 200 characters are rejected so the DRF target enforces the same strict constraints advertised by bridge v1. The global mutation opt-in enables every MCP mutation, not just this tool; a timeout or post-dispatch failure is ambiguous and must never be auto-retried. The tool is marked destructive because synchronization reconciliation can delete stale NetBox inventory records; it does not imply deletion of Proxmox guests or infrastructure. The concrete stage list selects only the 13 SSE stages. Endpoint preflight and scoped cluster/node, firewall, and datacenter reconciliation still run first; VM-template reconciliation also runs unless disabled by sync mode. The exact complete unique list becomes the internal ["all"] identity used by recurring hints and repair debounce, without making "all" valid MCP input.

Authentication¶

Authentication follows NetBox's LOGIN_REQUIRED setting through IsAuthenticatedOrLoginNotRequired. When LOGIN_REQUIRED=True, every endpoint requires authentication. A deployment that deliberately sets it to False may expose read-only descriptors such as the MCP manifest anonymously, but operation-specific permission checks still apply: both sync-job listing and scheduling require core.add_job regardless of that setting. Three authentication methods are supported when login is required:

Token authentication (recommended for automation):

curl -H "Authorization: Token <your-netbox-token>" \
     http://netbox.example.com/api/plugins/proxbox/proxmox-clusters/

Session authentication: Used automatically by the NetBox web UI. Browser requests that include a valid Django session cookie are accepted.

Object-level permissions: All viewsets use NetBoxModelViewSet, which enforces NetBox's object permission system via queryset.restrict(request.user, "view"). A user must have the corresponding view, add, change, or delete model permission to perform each operation.

Pagination¶

All list endpoints support NetBox's standard limit/offset pagination.

Parameter	Default	Description
`limit`	NetBox `PAGINATE_COUNT` setting	Number of results per page
`offset`	`0`	Number of results to skip

Response envelope:

{
  "count": 42,
  "next": "/api/plugins/proxbox/clusters/?limit=50&offset=50",
  "previous": null,
  "results": [...]
}

Search¶

All list endpoints accept a ?q= query parameter for free-text search. Each model defines its own set of searchable fields, documented per endpoint.

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/proxmox-clusters/?q=pve"

Common Response Fields¶

Every object in every endpoint includes these standard fields:

Field	Type	Description
`id`	integer	Unique database ID
`url`	string	Canonical API URL for this object
`display`	string	Human-readable label for the object
`tags`	array	List of NetBox tag objects
`custom_fields`	object	Key/value map of custom field values
`created`	datetime	ISO 8601 timestamp when the record was created
`last_updated`	datetime	ISO 8601 timestamp of the last modification

Nested Serializers¶

Foreign key fields are represented as nested objects in GET responses:

{
  "endpoint": {
    "id": 1,
    "url": "/api/plugins/proxbox/endpoints/proxmox/1/",
    "display": "prod-proxmox (10.0.0.1)",
    "name": "prod-proxmox"
  }
}

On write (POST, PUT, PATCH), these fields accept either the nested object or a plain integer ID:

{ "endpoint": 1 }

Write-Only Fields¶

Certain credential fields never appear in GET responses. They can only be set on POST, PUT, or PATCH:

Model	Write-Only Fields
`ProxmoxEndpoint`	`password`, `token_value`
`NetBoxEndpoint`	`token_secret`

Upsert Behavior¶

Two models perform an upsert on POST — if a matching record already exists by natural key, the POST updates it rather than returning a 400 conflict:

Model	Upsert Key
`ProxmoxStorage`	`(cluster, name)`
`VMTaskHistory`	`upid`

Endpoint Map¶

Path	Methods	Documentation
`/api/plugins/proxbox/`	GET	This page
`/api/plugins/proxbox/mcp/`	GET	Version 1 semantic-tool manifest for the netbox-sdk MCP bridge
`/api/plugins/proxbox/endpoints/`	GET	Endpoint Configuration
`/api/plugins/proxbox/endpoints/proxmox/`	GET POST	ProxmoxEndpoint
`/api/plugins/proxbox/endpoints/proxmox/{id}/`	GET PUT PATCH DELETE	ProxmoxEndpoint
`/api/plugins/proxbox/endpoints/netbox/`	GET POST	NetBoxEndpoint
`/api/plugins/proxbox/endpoints/netbox/{id}/`	GET PUT PATCH DELETE	NetBoxEndpoint
`/api/plugins/proxbox/endpoints/fastapi/`	GET POST	FastAPIEndpoint
`/api/plugins/proxbox/endpoints/fastapi/{id}/`	GET PUT PATCH DELETE	FastAPIEndpoint
`/api/plugins/proxbox/proxmox-clusters/`	GET POST	ProxmoxCluster
`/api/plugins/proxbox/proxmox-clusters/{id}/`	GET PUT PATCH DELETE	ProxmoxCluster
`/api/plugins/proxbox/proxmox-nodes/`	GET POST	ProxmoxNode
`/api/plugins/proxbox/proxmox-nodes/{id}/`	GET PUT PATCH DELETE	ProxmoxNode
`/api/plugins/proxbox/storage/`	GET POST	ProxmoxStorage
`/api/plugins/proxbox/storage/{id}/`	GET PUT PATCH DELETE	ProxmoxStorage
`/api/plugins/proxbox/backups/`	GET POST	VMBackup
`/api/plugins/proxbox/backups/{id}/`	GET PUT PATCH DELETE	VMBackup
`/api/plugins/proxbox/snapshots/`	GET POST	VMSnapshot
`/api/plugins/proxbox/snapshots/{id}/`	GET PUT PATCH DELETE	VMSnapshot
`/api/plugins/proxbox/task-history/`	GET POST	VMTaskHistory
`/api/plugins/proxbox/task-history/{id}/`	GET PUT PATCH DELETE	VMTaskHistory
`/api/plugins/proxbox/backup-routines/`	GET POST	BackupRoutine
`/api/plugins/proxbox/backup-routines/{id}/`	GET PUT PATCH DELETE	BackupRoutine
`/api/plugins/proxbox/replications/`	GET POST	Replication
`/api/plugins/proxbox/replications/{id}/`	GET PUT PATCH DELETE	Replication
`/api/plugins/proxbox/endpoints/proxmox/{id}/services/refresh/`	POST	Queue on-demand endpoint service monitoring via netbox-rpc
`/api/plugins/proxbox/service-collections/`	GET	Read-only Proxmox endpoint service collection history
`/api/plugins/proxbox/service-collections/{id}/`	GET	Read-only Proxmox endpoint service collection detail
`/api/plugins/proxbox/service-samples/`	GET	Read-only raw systemd service samples
`/api/plugins/proxbox/service-samples/{id}/`	GET	Read-only raw systemd service sample detail
`/api/plugins/proxbox/service-statuses/`	GET	Read-only latest projected systemd service status
`/api/plugins/proxbox/service-statuses/{id}/`	GET	Read-only latest projected systemd service status detail
`/api/plugins/proxbox/settings/`	GET	Plugin Settings
`/api/plugins/proxbox/settings/{id}/`	GET PATCH	Plugin Settings
`/api/plugins/proxbox/ha/summary/`	GET	Cluster HA
`/api/plugins/proxbox/ha/vm/{vmid}/`	GET	Cluster HA
`/api/plugins/proxbox/firecracker-host-pools/`	GET POST	FirecrackerHostPool CRUD
`/api/plugins/proxbox/firecracker-host-pools/{id}/`	GET PUT PATCH DELETE	FirecrackerHostPool CRUD
`/api/plugins/proxbox/firecracker-hosts/`	GET POST	FirecrackerHost CRUD
`/api/plugins/proxbox/firecracker-hosts/{id}/`	GET PUT PATCH DELETE	FirecrackerHost CRUD
`/api/plugins/proxbox/firecracker-image-templates/`	GET POST	FirecrackerImageTemplate CRUD
`/api/plugins/proxbox/firecracker-image-templates/{id}/`	GET PUT PATCH DELETE	FirecrackerImageTemplate CRUD
`/api/plugins/proxbox/firecracker-microvms/`	GET POST	FirecrackerMicroVM CRUD
`/api/plugins/proxbox/firecracker-microvms/{id}/`	GET PUT PATCH DELETE	FirecrackerMicroVM CRUD
`/api/plugins/proxbox/cloud-image-templates/`	GET POST	CloudImageTemplate CRUD
`/api/plugins/proxbox/cloud-image-templates/{id}/`	GET PUT PATCH DELETE	CloudImageTemplate CRUD
`/api/plugins/proxbox/vm-cloudinit/`	GET POST	ProxmoxVMCloudInit CRUD
`/api/plugins/proxbox/vm-cloudinit/{id}/`	GET PUT PATCH DELETE	ProxmoxVMCloudInit CRUD
`/api/plugins/proxbox/branch-intents/`	GET POST	ProxboxBranchIntent CRUD; soft branch reference must resolve
`/api/plugins/proxbox/branch-intents/{id}/`	GET PUT PATCH DELETE	ProxboxBranchIntent CRUD; branch reference is immutable
`/api/plugins/proxbox/vm-templates/`	GET POST	ProxmoxVMTemplate CRUD
`/api/plugins/proxbox/vm-templates/{id}/`	GET PUT PATCH DELETE	ProxmoxVMTemplate CRUD
`/api/plugins/proxbox/ssh-credentials/`	GET POST	NodeSSHCredential CRUD
`/api/plugins/proxbox/ssh-credentials/{id}/`	GET PUT PATCH DELETE	NodeSSHCredential CRUD
`/api/plugins/proxbox/ssh-credentials/by-node/{node_id}/`	GET	Lookup SSH credential by ProxmoxNode
`/api/plugins/proxbox/ssh-credentials/by-node/{node_id}/credentials/`	GET	Retrieve decrypted SSH credential secrets by node
`/api/plugins/proxbox/ssh-credentials/by-endpoint/{endpoint_id}/credentials/`	GET	Retrieve endpoint SSH secrets for browser terminal sessions; supports dedicated encrypted credentials or `ssh_credential_source=reuse_endpoint` with the same response shape
`/api/plugins/proxbox/firewall/security-groups/`	GET POST	ProxmoxFirewallSecurityGroup CRUD
`/api/plugins/proxbox/firewall/security-groups/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallSecurityGroup CRUD
`/api/plugins/proxbox/firewall/rules/`	GET POST	ProxmoxFirewallRule CRUD
`/api/plugins/proxbox/firewall/rules/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallRule CRUD
`/api/plugins/proxbox/firewall/ipsets/`	GET POST	ProxmoxFirewallIPSet CRUD
`/api/plugins/proxbox/firewall/ipsets/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallIPSet CRUD
`/api/plugins/proxbox/firewall/ipset-entries/`	GET POST	ProxmoxFirewallIPSetEntry CRUD
`/api/plugins/proxbox/firewall/ipset-entries/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallIPSetEntry CRUD
`/api/plugins/proxbox/firewall/aliases/`	GET POST	ProxmoxFirewallAlias CRUD
`/api/plugins/proxbox/firewall/aliases/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallAlias CRUD
`/api/plugins/proxbox/firewall/options/`	GET POST	ProxmoxFirewallOptions CRUD
`/api/plugins/proxbox/firewall/options/{id}/`	GET PUT PATCH DELETE	ProxmoxFirewallOptions CRUD
`/api/plugins/proxbox/sdn-fabrics/`	GET POST	ProxmoxSdnFabric CRUD
`/api/plugins/proxbox/sdn-fabrics/{id}/`	GET PUT PATCH DELETE	ProxmoxSdnFabric CRUD
`/api/plugins/proxbox/sdn-route-maps/`	GET POST	ProxmoxSdnRouteMap CRUD
`/api/plugins/proxbox/sdn-route-maps/{id}/`	GET PUT PATCH DELETE	ProxmoxSdnRouteMap CRUD
`/api/plugins/proxbox/sdn-prefix-lists/`	GET POST	ProxmoxSdnPrefixList CRUD
`/api/plugins/proxbox/sdn-prefix-lists/{id}/`	GET PUT PATCH DELETE	ProxmoxSdnPrefixList CRUD
`/api/plugins/proxbox/datacenter-cpu-models/`	GET POST	ProxmoxDatacenterCpuModel CRUD
`/api/plugins/proxbox/datacenter-cpu-models/{id}/`	GET PUT PATCH DELETE	ProxmoxDatacenterCpuModel CRUD
`/api/plugins/proxbox/resources/firecracker-microvms/`	GET	NMS-compatible Firecracker micro-VM list (non-model view)
`/api/plugins/proxbox/resources/interfaces/`	GET	Aggregated VM interface list (non-model view)
`/api/plugins/proxbox/resources/ip-addresses/`	GET	Aggregated IP address list (non-model view)
`/api/plugins/proxbox/resources/virtual-disks/`	GET	Aggregated virtual disk list (non-model view)
`/api/plugins/proxbox/deletion-requests/`	GET HEAD OPTIONS	DeletionRequest (read-only)
`/api/plugins/proxbox/deletion-requests/{id}/`	GET HEAD OPTIONS	DeletionRequest (read-only)
`/api/plugins/proxbox/apply-jobs/`	GET HEAD OPTIONS	ProxmoxApplyJob (read-only audit)
`/api/plugins/proxbox/apply-jobs/{id}/`	GET HEAD OPTIONS	ProxmoxApplyJob (read-only audit)

Deletion Requests and Apply Jobs (Read-Only)¶

DeletionRequest and ProxmoxApplyJob are the two read-only viewsets in the plugin. Their http_method_names is restricted to ["get", "head", "options"] — POST, PUT, PATCH, and DELETE return HTTP 405.

Why they are read-only¶

Both models form part of a five-lock deletion safety chain that prevents autonomous VM destruction. The chain requires separate actors, explicit confirmation phrases, and operator approval — no single API call (and no automated agent) can bypass it. Making the REST surface read-only enforces this at the framework level:

Lock	Mechanism
1 — Plugin setting	Master `allow_delete` toggle must be enabled in `ProxboxPluginSettings`
2 — Typed phrase	Caller must supply the exact phrase `allow-edit-and-add-actions` in the request
3 — Explicit flag	Request body must include `apply_destroy_confirmed: true`
4 — Requester permission	Initiating user must hold the `delete_deletion_request` permission
5 — Separate authorizer	A different user must approve (`self_approve_allowed: false`)

The DeletionRequest REST endpoint exists only for reading the current deletion queue. The actual deletion workflow is initiated through the NetBox UI or the intent API — not the plugin REST API. See the Deletion Requests guide for the complete four-eyes workflow.

ProxmoxApplyJob¶

ProxmoxApplyJob records the result of intent-branch apply operations (plan → apply cycles). It is written exclusively by the proxbox-api backend; the plugin REST surface is read-only so audit records cannot be tampered with through the API.

Example — list pending deletion requests:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/deletion-requests/?status=pending"

Example — retrieve an apply job result:

curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/apply-jobs/42/"