Skip to content

Proxmox OpenAPI

Schema-driven FastAPI package and Python SDK for Proxmox APIs: OpenAPI generation, mock data, real API connections, typed service facades, and a CLI/TUI built on the same backend layer.

Features

🔄 Auto-Generated OpenAPI Schema

Crawl the official Proxmox API Viewer and automatically generate complete OpenAPI 3.0 schemas with 675 operations across 449 endpoints.

Multi-Service SDK Facades

Use one backend layer across Proxmox VE (PVE), Proxmox Mail Gateway (PMG), Proxmox Backup Server (PBS), and Proxmox Datacenter Manager (PDM). Typed facades are available for PBS, PDM, and Ceph workflows that need a more structured interface than raw path navigation.

CLI and Textual TUIs

The proxmox, proxmox-cli, and pbx entry points expose generic API commands, profile management, command-capture docs generation, Ceph/PBS/PDM command groups, and production/mock TUIs.

🎭 Mock API Mode (Default)

Perfect for development and testing:

  • In-memory CRUD operations - Create, read, update, and delete mock Proxmox resources
  • Pre-generated 675 operations / 449 endpoints - Full Proxmox API surface ready to use
  • Custom mock data loading - Inject your own test data via JSON/YAML files
  • State persistence - Mock data persists across requests during runtime
  • No Proxmox server required - Test your code without a real Proxmox cluster

🔗 Real API Mode

Connect to actual Proxmox servers:

  • Full HTTP client with aiohttp - Efficient async connections
  • Request/response validation - Pydantic models ensure data integrity
  • Multiple auth methods - API tokens or username/password
  • SSL verification control - Flexible certificate handling
  • Production-ready - Battle-tested error handling and logging

📚 FastAPI Integration

  • Automatic Swagger UI at /docs - Interactive API exploration
  • ReDoc documentation at /redoc - Clean, readable API docs
  • OpenAPI JSON at /openapi.json - Machine-readable schema

Quick Start

Installation

pip install proxmox-sdk

Run Mock API (Default)

# Using the command-line tool
proxmox-sdk-mock

# Or with uvicorn directly
uvicorn proxmox_sdk.mock_main:app

Visit http://localhost:8000/docs to see 675 operations / 449 Proxmox API endpoints ready to use!

Connect to Real Proxmox

# Set environment variables
export PROXMOX_API_MODE=real
export PROXMOX_API_URL=https://pve.example.com:8006
export PROXMOX_API_TOKEN_ID=user@pam!mytoken
export PROXMOX_API_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Run the API
uvicorn proxmox_sdk.main:app

All requests now route to your real Proxmox server with full validation!

Use Cases

For Developers

  • Test Proxmox integrations without a real cluster
  • Prototype applications with full API mocking
  • CI/CD pipelines with consistent mock data
  • Local development without VPN/network access

For DevOps/SRE

  • API exploration with interactive Swagger docs
  • Schema validation for automation scripts
  • Custom tooling built on validated Proxmox operations
  • Production API proxy with request/response logging

For QA/Testing

  • Automated testing with reproducible mock data
  • Integration tests without environment dependencies
  • Load testing against mock endpoints
  • Regression testing with versioned schemas

Architecture

graph LR
    A[Client] --> B{Proxmox OpenAPI}
    B -->|Mock Mode| C[In-Memory CRUD]
    B -->|Real Mode| D[ProxmoxClient]
    D --> E[Real Proxmox Server]
    C --> F[Generated Mock Data]
    D --> G[Request Validation]
    G --> D
    D --> H[Response Validation]
    H --> A

Mock Mode: Requests → Generated Endpoints → In-Memory State → Mock Response

Real Mode: Requests → Validation → aiohttp Client → Proxmox API → Validation → Response

Documentation

Example: Create a VM (Mock Mode)

import httpx

# POST to create a VM
response = httpx.post(
    "http://localhost:8000/api2/json/nodes/pve/qemu",
    json={
        "vmid": 100,
        "name": "test-vm",
        "memory": 2048,
        "cores": 2,
    }
)

print(response.json())
# {'vmid': 100, 'name': 'test-vm', 'memory': 2048, 'cores': 2, ...}

# GET to retrieve the VM
response = httpx.get("http://localhost:8000/api2/json/nodes/pve/qemu/100")
print(response.json())
# Returns the same VM data - state persisted!

Example: Real Proxmox Connection

import os
from proxmox_sdk.main import create_app

# Configure real API connection
os.environ["PROXMOX_API_MODE"] = "real"
os.environ["PROXMOX_API_URL"] = "https://pve.example.com:8006"
os.environ["PROXMOX_API_TOKEN_ID"] = "user@pam!mytoken"
os.environ["PROXMOX_API_TOKEN_SECRET"] = "your-secret"

# Create app in real mode
app = create_app()

# Now all requests route to your real Proxmox server
# with full Pydantic validation on requests and responses!

Project Status

  • ✅ Stable: Mock API mode fully functional
  • ✅ Production Ready: Real API mode with validated HTTPS, SSH, local, and mock backends
  • 🔄 Active Development: Regular updates and improvements
  • 📦 PyPI Published: pip install proxmox-sdk

License

MIT License - see LICENSE file for details

Support

Next Steps