Proxmox API Automation with pvesh & Tokens

Everything the Proxmox web UI does goes through a REST API, which means you can script it too. Proxmox API automation is how you build VMs from templates on demand, plug Proxmox into tools like Terraform or Ansible, or write your own small panel.

Before you start

A Proxmox VE node or cluster.
An API token with only the permissions you need (users, permissions and API tokens).
curl and optionally jq on the machine that runs scripts.

Explore the API with pvesh

On a node, pvesh calls the API locally as root, which is a safe way to learn the paths:

pvesh get /nodes

pvesh get /cluster/resources --type vm

pvesh get /nodes/pve1/qemu/105/status/current

The built-in API viewer at https://YOUR_NODE:8006/pve-docs/api-viewer/ lists every endpoint and parameter.

Call the API remotely with a token

Tokens are sent in an Authorization header in the form PVEAPIToken=USER@REALM!TOKENID=SECRET:

curl -s -H "Authorization: PVEAPIToken=automation@pve!scripts=SECRET" https://pve1.example.com:8006/api2/json/nodes | jq .

Start a VM

curl -s -X POST -H "Authorization: PVEAPIToken=automation@pve!scripts=SECRET" https://pve1.example.com:8006/api2/json/nodes/pve1/qemu/105/status/start

Clone a template

curl -s -X POST -H "Authorization: PVEAPIToken=automation@pve!scripts=SECRET" -d newid=150 -d name=web3 -d full=1 https://pve1.example.com:8006/api2/json/nodes/pve1/qemu/9000/clone

Actions like start and clone return a task ID (UPID). Poll /nodes/pve1/tasks/UPID/status to know when they finish. Combine clones with cloud-init templates to set IPs and SSH keys automatically.

Warning: Keep a valid certificate on the node (Let's Encrypt SSL) instead of adding -k to skip certificate checks in production scripts.

Keep automation safe

One token per tool, with privilege separation and only the roles it needs (for example PVEVMAdmin on one pool).
Store secrets in a secrets manager or environment variables, not in scripts committed to Git.
Restrict API access to known IPs with the firewall.

Troubleshooting

401 no ticket: the header format is wrong; check the ! and = separators.
403 permission check failed: the token lacks permission on that path.
Parameter verification failed: a required parameter is missing; check the API viewer.

Frequently asked questions

Can I use Terraform with Proxmox?

Yes, community providers use this same API with tokens.

Is there an official client library?

Several community libraries exist for Python, Go and others; they wrap the same endpoints.

Does the API work across a cluster?

Yes, any node accepts calls for any node in the cluster.

Next steps

Was this guide helpful?

Still stuck?

Ask MdmHost AI for a quick answer, or open a ticket and our team will take a look. We are here 24/7.

Ask MdmHost AI Open a ticket