Sign in json response
Reference

REST API

A clean, token-authenticated REST API with a consistent envelope, far easier to automate against than raw Proxmox.

This page is the endpoint reference. For a high-level overview of what the API can do, see the REST API feature overview.

API version

Authentication

Create a token under Settings → API tokens in the panel, then send it as a bearer token on every request. In-app docs also live at /panel/api.

http 
Authorization: Bearer <your-api-token>

Response envelope

Every response uses the same envelope. On success error is null; on failure data is null and an HTTP error status is returned.

json 
{
  "success": true,
  "data": { },
  "error": null
}

v2 is coming soon

The next API version is in design. Until it ships, use v1. Switch the toggle above. v1 stays supported.

Hosts

GET /api/v1/hosts

List the configured Proxmox hosts (no secrets are ever returned).

curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}

Nodes

GET /api/v1/hosts/{id}/nodes

List the nodes belonging to a host.

ParameterTypeDescription
id integer Host id from GET /hosts.
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/nodes
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}
GET /api/v1/hosts/{id}/nodes/{node}

Read a single node by name.

ParameterTypeDescription
id integer Host id.
node string Node name (validated before use).
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/nodes/pve
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}

Guests

GET /api/v1/hosts/{id}/guests

List every VM and container on a host.

ParameterTypeDescription
id integer Host id.
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/guests
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}
GET /api/v1/hosts/{id}/guests/{type}/{vmid}

Read a single guest.

ParameterTypeDescription
id integer Host id.
type string qemu or lxc.
vmid integer Proxmox VM id.
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/guests/qemu/101
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}
POST /api/v1/hosts/{id}/guests

Create a guest on a host.

ParameterTypeDescription
id integer Host id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "node": "pve", "type": "qemu", "name": "web-01" }' \
  https://panel.example.com/api/v1/hosts/1/guests
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}
POST /api/v1/hosts/{id}/guests/{type}/{vmid}/reinstall

Reinstall a guest, keeping its id and specs.

ParameterTypeDescription
id integer Host id.
type string qemu or lxc.
vmid integer Proxmox VM id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "node": "pve", "type": "qemu", "name": "web-01" }' \
  https://panel.example.com/api/v1/hosts/1/guests
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}
DELETE /api/v1/hosts/{id}/guests/{type}/{vmid}

Delete a guest (zone IPs are released).

ParameterTypeDescription
id integer Host id.
type string qemu or lxc.
vmid integer Proxmox VM id.
curl 
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/guests/qemu/101
json response 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Frankfurt-1",
      "hostname": "10.0.0.10",
      "port": 8006,
      "user": "root@pam",
      "active": true
    }
  ],
  "error": null
}

Power

POST /api/v1/hosts/{id}/guests/{type}/{vmid}/power

Run a power action on a guest. Returns the Proxmox task id (UPID) to follow.

ParameterTypeDescription
id integer Host id.
type string qemu or lxc.
vmid integer Proxmox VM id.
node string Node the guest is on (required).
action string start, stop, shutdown, reboot, suspend or resume.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d 'node=pve&action=start' \
  https://panel.example.com/api/v1/hosts/1/guests/qemu/101/power
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}

Tasks

GET /api/v1/hosts/{id}/tasks/{node}/{upid}

Follow a running Proxmox task by its UPID (e.g. from a power action).

ParameterTypeDescription
id integer Host id.
node string Node name.
upid string URL-encoded Proxmox task id.
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/hosts/1/tasks/pve/UPID%3Apve%3A...
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}

Users

GET /api/v1/users

List customer users.

ParameterTypeDescription
id integer Host id.
node string Node name.
upid string URL-encoded Proxmox task id.
curl 
curl -H "Authorization: Bearer $TOKEN" \
  https://panel.example.com/api/v1/users
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}
POST /api/v1/users

Create a customer. A generated password is returned once.

ParameterTypeDescription
email string Customer email.
username string Login username.
user_id string Optional external id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '[email protected]&username=jane' \
  https://panel.example.com/api/v1/users
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}
POST /api/v1/users/{id}/guests

Assign guest ownership to a user.

ParameterTypeDescription
id integer User id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '[email protected]&username=jane' \
  https://panel.example.com/api/v1/users
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}
DELETE /api/v1/users/{id}

Delete a customer user.

ParameterTypeDescription
id integer User id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '[email protected]&username=jane' \
  https://panel.example.com/api/v1/users
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}

Agent

POST /api/v1/agent/heartbeat

Used by the on-host NexoVirt agent. It authenticates with its own agent token (not an API token) and receives any pending jobs in the response. You normally never call this directly.

ParameterTypeDescription
id integer User id.
curl 
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '[email protected]&username=jane' \
  https://panel.example.com/api/v1/users
json response 
{
  "success": true,
  "data": { "upid": "UPID:pve:..." },
  "error": null
}
This documentation describes NexoVirt as it stands today and grows with it. Something missing? Get started free.
On this page