A cleaner REST API for Proxmox VE

Proxmox VE ships with a comprehensive REST API that exposes almost every operation the web interface can perform. But if you have ever tried to drive it from a script or integrate it into a billing system, you know the friction: ticket-and-CSRF authentication that expires and must be refreshed, per-node URL paths that require you to know the cluster topology in advance, response shapes that vary by endpoint, and no central place to read the docs while you code. The API is powerful. It is just not designed for the integrator sitting outside the Proxmox stack.

What Makes the Raw Proxmox API Hard to Work With

The native Proxmox VE API is designed to serve the Proxmox web UI, which means its authentication model reflects that. To make an authenticated request you first POST /api2/json/access/ticket with a username and password, receive a PVEAuthCookie and a CSRFPreventionToken, attach both to every subsequent write request, and then handle the fact that tickets expire after two hours. For a human session this is fine. For a long-running automation process it is plumbing you have to write and maintain yourself.

Beyond authentication, the resource hierarchy is host-specific. Every URL is scoped to a node: /nodes/{node}/qemu/{vmid}/status/start. If you manage multiple Proxmox hosts or a cluster with several nodes, your client has to track which node owns which guest and route requests accordingly. There is no single endpoint that says "start guest 105, wherever it lives." Response shapes also differ between resource types: some return a data key, some return task UPIDs directly, some return lists with varying field names, so defensive parsing becomes a project of its own.

None of this is a bug; it is the cost of a general-purpose API that exposes everything. The problem arises when you want to build on top of Proxmox quickly and predictably.

A Cleaner Layer: What NexoVirt Adds

NexoVirt is a self-hosted control panel for Proxmox VE that also ships a clean REST API sitting in front of the native Proxmox API. The goal is not to replace the Proxmox API. It is to give integrators a stable, predictable surface without making them care about tickets, CSRF tokens, or node routing. For a product-level overview, see the Proxmox REST API feature page.

Bearer Tokens Instead of the Ticket Dance

Authentication is a single Authorization: Bearer <token> header. Tokens are created in the NexoVirt settings panel and have no expiry by default. Your script or service sets the header once and never has to refresh it. The ticket-and-CSRF negotiation with Proxmox happens server-side, out of your way.

A Consistent Response Envelope

Every endpoint returns the same shape:

{
  "success": true,
  "data": {
    "vmid": 105,
    "name": "web-01",
    "status": "running",
    "node": "pve-node1"
  },
  "error": null
}

On failure, success is false, data is null, and error carries a human-readable message. You parse the envelope once and reuse the same logic everywhere. No special-casing per endpoint.

Simpler Resource Paths

The API is organised around the resources you actually care about as an operator or integrator: hosts, nodes on a host, guests on a host, power actions on a guest, and task status. You address guests through the host they belong to: GET /api/v1/hosts/{id}/guests returns all VMs and containers across every node on that host. Power actions follow the same pattern: POST /api/v1/hosts/{id}/guests/{type}/{vmid}/power with a JSON body specifying the node and action. You do not have to know or care which physical node a guest lives on at the call site; NexoVirt resolves that internally.

In-App Documentation

The API reference is built into the panel at /panel/api. It documents every endpoint, the accepted parameters, and example responses. You can read the docs while you are logged into the same instance you are building against, no external doc site to cross-reference.

What You Can Build With It

The consistent envelope and bearer-token authentication make a few categories of integration significantly easier:

• Automation and infrastructure-as-code. A provisioning script can create a guest, poll the task endpoint until the job completes, and react to the result, all with straightforward HTTP and a single token. No session management, no node-lookup step.
• Billing and hosting panels. Hosting providers running Proxmox often need a provisioning API their own control panel can call. NexoVirt exposes guest lifecycle (create, reinstall, delete, power) plus plan enforcement and IPAM, so a billing system can drive the full customer VM lifecycle without touching Proxmox directly.
• Dashboards and monitoring. Because the API returns consistent data shapes, feeding guest and node status into an external dashboard or alerting system requires no per-endpoint adapters. Poll GET /api/v1/hosts/{id}/guests on an interval and you get a unified inventory across all your Proxmox hosts.
• Internal tooling and scripts. Ops teams often build small internal tools: a Slack bot that can reboot a guest, a deploy pipeline that provisions a staging VM and tears it down after the build. These are straightforward to implement against a predictable API that does not require ticket refresh logic.

A Thin Layer, Not a Walled Garden

It is worth being direct about what NexoVirt's API is and is not. It is a thin, opinionated layer over the Proxmox VE API, implemented as a Guzzle-based PHP wrapper that handles authentication and request routing, not a new hypervisor management system. Every action it takes ultimately calls the native Proxmox API. You are not locked into NexoVirt's abstractions for everything; the Proxmox web UI and native API remain fully accessible. NexoVirt adds convenience and consistency for the operations you want to automate, while leaving the rest of the Proxmox ecosystem untouched.

If you manage multiple Proxmox hosts, the multi-host model is particularly useful: a single API token gives you access to guests and nodes across all connected hosts. The discovery agent imports existing VMs, containers, storage, and networks without requiring any reinstall, so you can point NexoVirt at an existing Proxmox environment and have a working API surface within minutes.

More detail on the available endpoints is in the documentation, and the full feature set, RBAC, customer portal, IPAM, NAT, alerting, Plans with enforcement, is covered on the features page.

NexoVirt is available now. Community Edition is free (up to 2 nodes). If you are running Proxmox and want a cleaner API surface for your automation or provisioning work, get started free and try it against your own infrastructure.