Proxmox API: Complete Developer Guide

Proxmox VE API Overview

Proxmox VE exposes a comprehensive REST API that gives you programmatic control over every aspect of your virtualization infrastructure. Every action you can perform in the web UI — creating VMs, managing storage, configuring networks, taking snapshots — is available through the API. This makes Proxmox highly automatable and easy to integrate with external tools, scripts, and platforms.

The API is served over HTTPS on port 8006, the same port as the web UI. It accepts and returns JSON, follows RESTful conventions, and includes built-in API documentation at https://your-server:8006/pve-docs/api-viewer/.

Authentication Methods

Proxmox offers two authentication methods for the API, each suited to different use cases.

Ticket-Based Authentication

Ticket authentication works like a session. You send your username and password to get a ticket (cookie) and a CSRF prevention token, then include both in subsequent requests. Tickets expire after two hours.

# Get an authentication ticket
curl -k -d "username=root@pam&password=yourpassword" \
  https://10.0.0.1:8006/api2/json/access/ticket

# Response includes:
# "ticket": "PVE:root@pam:6789ABCD::..."
# "CSRFPreventionToken": "6789ABCD:..."

Use the ticket in subsequent requests:

curl -k -b "PVEAuthCookie=PVE:root@pam:6789ABCD::..." \
  -H "CSRFPreventionToken: 6789ABCD:..." \
  https://10.0.0.1:8006/api2/json/nodes

API Token Authentication (Recommended)

API tokens are persistent credentials that do not expire and do not require a login step. They are the preferred method for scripts, automation, and third-party integrations. Each token can have its own permissions, separate from the user account.

Create an API token through the web UI (Datacenter > Permissions > API Tokens) or via the CLI:

# Create an API token for the root user
pveum user token add root@pam automation --privsep=0

# Output:
# Token ID: root@pam!automation
# Token Secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The --privsep=0 flag gives the token the same permissions as the user. Set --privsep=1 to create a token with separate (more restrictive) privileges.

Use the token in API requests with the Authorization header:

curl -k -H "Authorization: PVEAPIToken=root@pam!automation=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  https://10.0.0.1:8006/api2/json/nodes

Security tip: For production environments, create a dedicated API user with minimal permissions rather than using root. Assign only the privileges the token needs — for example, read-only access for monitoring tools.

Essential API Endpoints

Here are the most commonly used API endpoints organized by function:

Cluster and Node Information

# List all nodes in the cluster
GET /api2/json/nodes

# Get detailed status for a specific node
GET /api2/json/nodes/{node}/status

# Get node resource usage (CPU, memory, disk)
GET /api2/json/nodes/{node}/rrddata?timeframe=hour

Virtual Machine Management

# List all VMs on a node
GET /api2/json/nodes/{node}/qemu

# Get VM status and config
GET /api2/json/nodes/{node}/qemu/{vmid}/status/current
GET /api2/json/nodes/{node}/qemu/{vmid}/config

# Start, stop, shutdown, reset a VM
POST /api2/json/nodes/{node}/qemu/{vmid}/status/start
POST /api2/json/nodes/{node}/qemu/{vmid}/status/stop
POST /api2/json/nodes/{node}/qemu/{vmid}/status/shutdown
POST /api2/json/nodes/{node}/qemu/{vmid}/status/reset

# Create a snapshot
POST /api2/json/nodes/{node}/qemu/{vmid}/snapshot
  Body: snapname=before-update&description=Pre-update snapshot

LXC Container Management

# List all containers on a node
GET /api2/json/nodes/{node}/lxc

# Get container status
GET /api2/json/nodes/{node}/lxc/{vmid}/status/current

# Start/stop a container
POST /api2/json/nodes/{node}/lxc/{vmid}/status/start
POST /api2/json/nodes/{node}/lxc/{vmid}/status/stop

Storage

# List all storage
GET /api2/json/nodes/{node}/storage

# Get storage content (ISOs, backups, disk images)
GET /api2/json/nodes/{node}/storage/{storage}/content

# Get storage status (usage, available space)
GET /api2/json/nodes/{node}/storage/{storage}/status

Tasks

# List recent tasks
GET /api2/json/nodes/{node}/tasks

# Get task status (for tracking async operations)
GET /api2/json/nodes/{node}/tasks/{upid}/status

# Get task log
GET /api2/json/nodes/{node}/tasks/{upid}/log

Practical Examples

Bash: Bulk Start All VMs

#!/bin/bash
API_URL="https://10.0.0.1:8006/api2/json"
TOKEN="PVEAPIToken=root@pam!automation=xxxxx-xxxxx-xxxxx"
NODE="pve"

# Get list of all stopped VMs
VMIDS=$(curl -s -k -H "Authorization: $TOKEN" \
  "$API_URL/nodes/$NODE/qemu" | \
  jq -r '.data[] | select(.status=="stopped") | .vmid')

# Start each one
for VMID in $VMIDS; do
    echo "Starting VM $VMID..."
    curl -s -k -X POST -H "Authorization: $TOKEN" \
      "$API_URL/nodes/$NODE/qemu/$VMID/status/start"
done

Python: Monitor Node Resources

import requests
import urllib3
urllib3.disable_warnings()

API_URL = "https://10.0.0.1:8006/api2/json"
HEADERS = {
    "Authorization": "PVEAPIToken=root@pam!automation=xxxxx-xxxxx-xxxxx"
}

# Get node status
response = requests.get(f"{API_URL}/nodes/pve/status", headers=HEADERS, verify=False)
data = response.json()["data"]

cpu_usage = data["cpu"] * 100
memory_used = data["memory"]["used"] / (1024**3)
memory_total = data["memory"]["total"] / (1024**3)

print(f"CPU Usage: {cpu_usage:.1f}%")
print(f"Memory: {memory_used:.1f} / {memory_total:.1f} GB")

# List all VMs and their status
response = requests.get(f"{API_URL}/nodes/pve/qemu", headers=HEADERS, verify=False)
for vm in response.json()["data"]:
    print(f"VM {vm['vmid']} ({vm['name']}): {vm['status']}")

Python: Create a VM from Template

import requests
urllib3.disable_warnings()

API_URL = "https://10.0.0.1:8006/api2/json"
HEADERS = {
    "Authorization": "PVEAPIToken=root@pam!automation=xxxxx-xxxxx-xxxxx"
}

# Clone from template 9000
clone_data = {
    "newid": 150,
    "name": "new-web-server",
    "full": 1,
    "target": "pve"
}

response = requests.post(
    f"{API_URL}/nodes/pve/qemu/9000/clone",
    headers=HEADERS, data=clone_data, verify=False
)
print(f"Clone task: {response.json()['data']}")

Mobile API Access with ProxmoxR

While curl scripts and Python are great for automation, there are times when you need quick API-level access from your phone — checking VM status, starting a stopped service, or monitoring node resources while you are away from your terminal. ProxmoxR is a mobile client built specifically for the Proxmox API. It connects using the same API tokens described in this guide and gives you a clean, native interface for the most common API operations: viewing nodes and VMs, starting and stopping machines, checking resource usage, and reviewing task logs. Instead of writing curl commands on a mobile keyboard, you get a purpose-built interface that handles authentication and API calls behind the scenes.

To connect ProxmoxR to your server, simply create an API token as described above and enter your server URL and token credentials in the app. This is particularly useful for on-call administrators who need to respond to alerts quickly without opening a laptop.

Rate Limiting and Best Practices

• Avoid polling too frequently: The Proxmox API does not impose hard rate limits, but rapid polling (sub-second intervals) adds unnecessary load. Poll every 5-10 seconds for status updates.
• Use task tracking for async operations: Operations like VM start, clone, and backup return a task UPID immediately. Poll the task status endpoint to check completion rather than repeatedly checking VM status.
• Handle self-signed certificates: By default, Proxmox uses a self-signed SSL certificate. In scripts, you will need to skip verification (-k in curl, verify=False in Python) or install the certificate in your trust store.
• Use the least privilege: Create API tokens with --privsep=1 and assign only the permissions needed. For a monitoring-only token, assign PVEAuditor role.
• Prefer API tokens over ticket auth: Tokens do not expire, are easier to manage, and can be revoked individually without affecting the user account.

Summary

The Proxmox VE REST API is one of the platform's greatest strengths. It enables everything from simple monitoring scripts to full infrastructure-as-code pipelines. By creating dedicated API tokens with appropriate permissions, you can safely automate VM provisioning, monitor cluster health, integrate with CI/CD systems, and manage your infrastructure from any device. Whether you are writing Python scripts on your workstation or using a mobile client like ProxmoxR to handle an urgent issue on the go, the API gives you complete control over your Proxmox environment.