Complete OpenAPI 3.0.3 specifications for Proxmox APIs, automatically generated from official documentation.
This repository provides comprehensive OpenAPI specifications for:
- Proxmox Virtual Environment (PVE) - VM and container management
- Proxmox Backup Server (PBS) - Backup and data protection
Both specifications are available in JSON and YAML formats with proper naming conventions:
pve-api.json/pve-api.yamlpbs-api.json/pbs-api.yaml
# Clone the repository
git clone https://github.com/basher83/Proxmox-OpenAPI.git
cd Proxmox-OpenAPI
# Use PVE specification
curl -o pve-spec.json https://raw.githubusercontent.com/basher83/Proxmox-OpenAPI/main/proxmox-virtual-environment/pve-api.json
# Use PBS specification
curl -o pbs-spec.json https://raw.githubusercontent.com/basher83/Proxmox-OpenAPI/main/proxmox-backup-server/pbs-api.json# Generate Python client for PVE
openapi-generator-cli generate \
-i proxmox-virtual-environment/pve-api.yaml \
-g python \
-o ./pve-client
# Generate Python client for PBS
openapi-generator-cli generate \
-i proxmox-backup-server/pbs-api.yaml \
-g python \
-o ./pbs-client| API | Endpoints | Operations | Size (JSON) | Size (YAML) | Port |
|---|---|---|---|---|---|
| PVE | 385 | 687 | 1.8MB | 1.2MB | 8006 |
| PBS | 233 | 348 | 1.1MB | 821KB | 8007 |
Proxmox-OpenAPI/
├── proxmox-virtual-environment/ # PVE API specifications
│ ├── pve-api.json # PVE OpenAPI JSON spec
│ ├── pve-api.yaml # PVE OpenAPI YAML spec
│ ├── apidoc.js # Source API documentation
│ └── README.md # PVE-specific documentation
├── proxmox-backup-server/ # PBS API specifications
│ ├── pbs-api.json # PBS OpenAPI JSON spec
│ ├── pbs-api.yaml # PBS OpenAPI YAML spec
│ ├── apidoc.js # Source API documentation
│ └── README.md # PBS-specific documentation
├── scripts/ # Generation scripts
│ ├── pve/ # PVE OpenAPI generation scripts
│ │ ├── generate_openapi.py # Main PVE OpenAPI generator
│ │ └── convert_to_yaml.py # JSON to YAML converter
│ └── pbs/ # PBS OpenAPI generation scripts
│ ├── generate_openapi.py # Main PBS OpenAPI generator
│ └── convert_to_yaml.py # JSON to YAML converter
├── .github/workflows/ # CI/CD automation (planned)
├── LICENSE # AGPL-3.0 license
└── README.md # This file
- Python 3.8+
- UV (recommended) or pip
- Node.js (optional, for enhanced JavaScript parsing)
# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and setup the project
git clone https://github.com/basher83/Proxmox-OpenAPI.git
cd Proxmox-OpenAPI
# Install dependencies
uv sync
# Install with development dependencies
uv sync --extra dev
# Install all optional dependencies
uv sync --extra all# PVE APIcd scripts/pve
uv run python generate_openapi.py
uv run python convert_to_yaml.py
# PBS APIcd scripts/pbs
uv run python generate_openapi.py
uv run python convert_to_yaml.py
# Or use the unified parser (future)
uv run proxmox-openapi pve proxmox-virtual-environment/apidoc.js proxmox-virtual-environment/
uv run proxmox-openapi pbs proxmox-backup-server/apidoc.js proxmox-backup-server/# PVE APIcd scripts/pve
python3 generate_openapi.py
python3 convert_to_yaml.py
# PBS APIcd scripts/pbs
python3 generate_openapi.py
python3 convert_to_yaml.pyA unified parsing framework is being developed to reduce code duplication and standardize the generation process across both APIs.
Each API has detailed documentation in its respective directory:
- PVE API Documentation - Virtual Environment management
- PBS API Documentation - Backup Server operations
Both APIs support multiple authentication methods:
- API Token:
PVEAPIToken=USER@REALM!TOKENID=UUID - Session Cookie: From
/access/ticketendpoint - CSRF Token: Required for state-changing operations
- API Token: Header-based token authentication
- Session Cookie: From
/access/ticketendpoint - CSRF Protection: Required for state-changing operations
curl -k -H "Authorization: PVEAPIToken=USER@REALM!TOKENID=UUID" \
https://your-pve-server:8006/api2/json/nodes/nodename/qemucurl -k -H "Authorization: PBSAPIToken=USER@REALM!TOKENID=UUID" \
https://your-pbs-server:8007/api2/json/admin/datastoreSee our detailed ROADMAP.md for feature tracking, implementation plans, and release timeline.
Current Priorities:
- ✅ Unified Parser Framework - Completed in v1.0
⚠️ CI/CD Pipeline Enhancements - Auto-PR creation and monitoring- ❌ Direct API Fetching - Parse from live Proxmox instances
- ❌ Enhanced Validation - Semantic validation and breaking change detection
- ❌ Client Libraries - Python, Go, and TypeScript
- ❌ Docker Images - Containerized tools for consistent environments
- Fork the repository
- Create a feature branch:
git checkout -b feature/improvement - Make your changes ensuring compatibility with official Proxmox APIs
- Validate specifications using OpenAPI tools
- Update documentation as needed
- Submit a pull request
For a detailed history of changes, see our CHANGELOG.
- Follow the Git Commit Workflow - Comprehensive commit standards and quality gates
- Maintain compatibility with official Proxmox API documentation
- Follow OpenAPI 3.0.3 specification standards
- Update both JSON and YAML formats
- Include appropriate tests and validation
- Update relevant README files
Use the automated validation script before committing:
# Run all quality checks
./scripts/validate-commit.sh
# Run checks and commit with template
./scripts/validate-commit.sh --commitThis project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.
The specifications are generated from official Proxmox documentation and follow the same AGPL-3.0 licensing terms as the source material.
- Proxmox VE API Viewer - Official PVE API documentation
- Proxmox PBS API Viewer - Official PBS API documentation
- OpenAPI Specification - OpenAPI 3.0.3 standard
- OpenAPI Generator - Code generation tools
- Proxmox Website - Official Proxmox resources
For issues related to:
- OpenAPI specifications: Open an issue in this repository
- Proxmox APIs: Contact Proxmox Support
- OpenAPI standard: Refer to OpenAPI documentation
Generated: 2025-01-28
Status: ✅ Production Ready
Maintainer: basher83