API Reference¶

This page provides a comprehensive reference of all available endpoints in the Proxmox OpenAPI server.

Endpoint Overview¶

The server provides 675 operations / 444 Proxmox VE API endpoints organized into the following categories:

Access Control - Users, groups, roles, permissions, ACLs
Cluster - Cluster configuration, HA, resources, firewall
Nodes - Node management, services, tasks, storage
Storage - Storage configuration and content management
Virtual Machines (VMs) - VM lifecycle, configuration, snapshots
Containers (LXC) - Container lifecycle, configuration, snapshots
Network - SDN, VLANs, zones, subnets
Pools - Resource pools
Version - API version information

Interactive Documentation¶

The best way to explore the API is through the interactive Swagger UI included with the server:

# Start the server
uvicorn proxmox_sdk.main:app --reload

# Open in browser
http://localhost:8000/docs

The Swagger UI provides:

Complete endpoint list with descriptions
Request/response schemas for all operations
Try-it-out functionality to test endpoints
Example request/response payloads
Authentication configuration

Common Endpoints¶

Version Information¶

GET /version

Returns Proxmox VE API version information.

Response:

{
  "version": "9.2",
  "release": "1",
  "repoid": "abc123"
}

Access Tickets (Authentication)¶

POST /access/ticket

Create authentication ticket (username/password login).

Request Body:

{
  "username": "root@pam",
  "password": "your-password"
}

Response:

{
  "ticket": "PVE:root@pam:...",
  "CSRFPreventionToken": "...",
  "username": "root@pam"
}

Cluster Status¶

GET /cluster/status

Get cluster status information.

Response:

[
  {
    "type": "cluster",
    "name": "proxmox-cluster",
    "quorate": 1,
    "nodes": 3
  }
]

Node List¶

GET /nodes

List all nodes in the cluster.

Response:

[
  {
    "node": "pve1",
    "status": "online",
    "cpu": 0.05,
    "maxcpu": 8,
    "mem": 8589934592,
    "maxmem": 34359738368
  }
]

Virtual Machine List¶

GET /nodes/{node}/qemu

List all VMs on a specific node.

Path Parameters: - node (string, required) - Node name

Response:

[
  {
    "vmid": 100,
    "name": "vm-test",
    "status": "running",
    "cpu": 0.02,
    "maxcpu": 2,
    "mem": 2147483648,
    "maxmem": 4294967296
  }
]

Create Virtual Machine¶

POST /nodes/{node}/qemu

Create a new virtual machine.

Path Parameters: - node (string, required) - Node name

Request Body:

{
  "vmid": 100,
  "name": "new-vm",
  "memory": 4096,
  "cores": 2,
  "sockets": 1,
  "ostype": "l26",
  "net0": "virtio,bridge=vmbr0",
  "scsi0": "local-lvm:32",
  "ide2": "local:iso/debian-12.0.0-amd64-netinst.iso,media=cdrom"
}

Response:

{
  "success": true,
  "vmid": 100
}

VM Configuration¶

GET /nodes/{node}/qemu/{vmid}/config

Get VM configuration.

Path Parameters: - node (string, required) - Node name - vmid (integer, required) - VM ID

Response:

{
  "vmid": 100,
  "name": "vm-test",
  "memory": 4096,
  "cores": 2,
  "sockets": 1,
  "bootdisk": "scsi0",
  "net0": "virtio=AA:BB:CC:DD:EE:FF,bridge=vmbr0"
}

VM Start/Stop/Reboot¶

POST /nodes/{node}/qemu/{vmid}/status/start
POST /nodes/{node}/qemu/{vmid}/status/stop
POST /nodes/{node}/qemu/{vmid}/status/reboot
POST /nodes/{node}/qemu/{vmid}/status/shutdown

Control VM power state.

Path Parameters: - node (string, required) - Node name - vmid (integer, required) - VM ID

Response:

{
  "success": true,
  "task": "UPID:pve1:..."
}

Container (LXC) List¶

GET /nodes/{node}/lxc

List all containers on a specific node.

Path Parameters: - node (string, required) - Node name

Response:

[
  {
    "vmid": 200,
    "name": "container-test",
    "status": "running",
    "cpu": 0.01,
    "maxcpu": 2,
    "mem": 536870912,
    "maxmem": 2147483648
  }
]

Storage List¶

GET /nodes/{node}/storage

List storage on a specific node.

Path Parameters: - node (string, required) - Node name

Response:

[
  {
    "storage": "local",
    "type": "dir",
    "content": "vztmpl,iso,backup",
    "active": 1,
    "total": 107374182400,
    "used": 21474836480,
    "avail": 85899345920
  }
]

Tasks¶

GET /nodes/{node}/tasks
GET /nodes/{node}/tasks/{upid}/status
GET /nodes/{node}/tasks/{upid}/log

View and monitor tasks.

Response (task list):

[
  {
    "upid": "UPID:pve1:...",
    "type": "qmstart",
    "id": "100",
    "user": "root@pam",
    "status": "running",
    "starttime": 1704067200
  }
]

Authentication¶

Most endpoints require authentication. See the Real API Guide for details on:

API token authentication
Username/password authentication
Setting up credentials

Response Codes¶

The API uses standard HTTP response codes:

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing or invalid authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable Entity - Pydantic request validation failed
`500`	Internal Server Error

Pagination¶

Some endpoints support pagination via query parameters:

limit - Maximum number of results (default: varies by endpoint)
start - Starting offset (default: 0)

Example:

GET /nodes/pve1/qemu?limit=10&start=0

Filtering¶

Many list endpoints support filtering via query parameters. Check the Swagger UI for available filters per endpoint.

Error Responses¶

Error responses follow this format:

{
  "detail": "Error message describing what went wrong",
  "errors": [
    {
      "field": "vmid",
      "message": "VM ID already exists"
    }
  ]
}

Schema Models¶

All request and response schemas are validated using Pydantic models. You can find the complete model definitions in:

Swagger UI - Interactive schema browser at /docs
ReDoc - Alternative documentation at /redoc
OpenAPI JSON - Raw schema at /openapi.json

Mock vs Real Mode¶

The behavior of endpoints differs based on the mode:

Mock Mode (Default)¶

In-memory CRUD operations
No actual Proxmox connection required
Data resets on server restart
Perfect for development and testing

Real Mode¶

Proxies requests to real Proxmox VE API
Requires valid Proxmox credentials
Full request/response validation
Production-ready

See the Mock API Guide and Real API Guide for mode-specific details.

Rate Limiting¶

Proxmox API proxy endpoints have no rate limiting. The /codegen/* endpoints are rate-limited via SlowAPI:

Endpoint	Limit
`POST /codegen/generate`	1 / hour
`GET /codegen/pydantic`	5 / hour
`GET /codegen/openapi`	5 / hour

See Security for details.

Redirect Policy¶

Every SDK-owned HTTP transport refuses every HTTP 3xx response, including 304 Not Modified, and raises ProxmoxRedirectError before reading the response body. This includes ordinary and bounded HTTPS requests, the ticket-authentication endpoint, multipart uploads, direct Ceph Dashboard/RGW/RBD provider requests, checksum auto-discovery probes, and codegen apidoc.js downloads. The transports never forward authentication cookies, CSRF headers, Dashboard credentials or bearer tokens, RGW authorization headers, upload bodies, or checksum probes through a redirect. A public checksum URL that redirects to a loopback or private address fails with the same typed exception. The exception reports the status and destination hostname without retaining the full Location value.

Versioning¶

The API follows the Proxmox VE API versioning scheme. The current implementation is based on Proxmox VE 9.2 (with latest mirroring 9.2; 9.1.11 retained).

For the most up-to-date endpoint reference, always check the Swagger UI at /docs when running the server.