Api

API Documentation

API documentation for Proxmox and Docker management endpoints.

Proxmox LXC Container Management API

Interactive API documentation for managing Proxmox LXC containers across your homelab infrastructure.

Hosts: - Primary: ...: (node: tower, token: root@pam) - Secondary: ...: (node: pve, token: automation@pve)

View API Spec (YAML) | Test in Swagger Editor

Browser Limitations

The Swagger UI below is for documentation only. Due to browser security restrictions (CORS and self-signed certificates), you cannot make live API calls directly from this page.

Command Execution Limitation

IMPORTANT: The Proxmox API does NOT provide endpoints to execute arbitrary commands inside LXC containers.

The /nodes/{node}/execute endpoint is for batch API calls, not shell commands. To run commands inside containers:

Option : SSH to Container (Recommended)

Bash
 SSH directly to the container
ssh root@...

 Or run single command
ssh root@... 'docker ps'

Option : pct exec from Proxmox Host

Bash
 From Proxmox host CLI
pct exec  -- ls -al
pct exec  -- bash -c 'docker ps'
pct exec  -- bash -c 'df -h'

Option : Your Existing p Script Your p script already uses SSH - this is the correct approach!

API Capabilities

The Proxmox API CAN do: - List containers - Start/stop/reboot containers - Get container status and stats - View container configuration - Monitor resources (CPU, RAM, disk, network) - Manage storage

The Proxmox API CANNOT do: - Execute shell commands in LXC containers - Access container filesystems directly - Run Docker commands inside containers

For VMs (not LXC), you can install qemu-guest-agent which provides /nodes/{node}/qemu/{vmid}/agent/exec endpoint.

Use these methods instead:

curl Examples

Bash
 List containers on tower (...)
curl -k -H "Authorization: PVEAPIToken=root@pam!homelab-hub=bddb-b--ab-afdaed" \
  https://...:/api/json/nodes/tower/lxc

 List containers on pve (...)
curl -k -H "Authorization: PVEAPIToken=automation@pve!api-token=aee-b---cddb" \
  https://...:/api/json/nodes/pve/lxc

 Start container  on pve
curl -k -X POST -H "Authorization: PVEAPIToken=automation@pve!api-token=aee-b---cddb" \
  https://...:/api/json/nodes/pve/lxc//status/start

 Get container status
curl -k -H "Authorization: PVEAPIToken=automation@pve!api-token=aee-b---cddb" \
  https://...:/api/json/nodes/pve/lxc//status/current

Postman / Insomnia - Import the proxmox-api.yaml file - Disable SSL certificate verification in settings - Make requests with proper Authorization headers

Docker Management

For Docker container management, consider these options:

. Portainer API Recommended - Full-featured Docker management API

  • Installation: docker run -d -p : -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce
  • API Docs: https://docs.portainer.io/api/api-docs
  • Features:
  • Container lifecycle (start, stop, restart, kill)
  • Image management (pull, build, push)
  • Volume and network management
  • Stack deployment
  • Container logs and stats
  • Real-time metrics

Key Endpoints:

Text Only
GET    /api/endpoints
GET    /api/endpoints/{id}/docker/containers/json
POST   /api/endpoints/{id}/docker/containers/{id}/start
POST   /api/endpoints/{id}/docker/containers/{id}/stop
POST   /api/endpoints/{id}/docker/containers/{id}/restart
GET    /api/endpoints/{id}/docker/containers/{id}/logs
GET    /api/endpoints/{id}/docker/containers/{id}/stats

. Docker Engine API Native - Direct Docker API access

  • Access: Unix socket /var/run/docker.sock or TCP http://localhost:
  • API Docs: https://docs.docker.com/engine/api/
  • Features:
  • Complete Docker functionality
  • Container operations
  • Image management
  • System info and monitoring
  • Events streaming

Key Endpoints:

Text Only
GET    /containers/json                     List containers
POST   /containers/{id}/start              Start container
POST   /containers/{id}/stop               Stop container
POST   /containers/{id}/restart            Restart container
GET    /containers/{id}/logs               Get logs
GET    /containers/{id}/stats              Get stats
POST   /images/create                      Pull image
GET    /system/df                          Disk usage

. Yacht Lightweight - Simple Docker management UI with API

  • Installation: docker run -d -p : -v /var/run/docker.sock:/var/run/docker.sock selfhostedpro/yacht
  • Features: Container management, template support, simple API

Recommendation

Use Portainer if you want: - Web UI + API - Multi-host management - Role-based access control - Easy setup

Use Docker Engine API directly if you want: - Minimal overhead - Native Docker functionality - Custom integrations

Use SSH + Docker CLI if you want: - Simplest approach - What your p script already does - Direct control