Proxmox API create VM cluster not per node: why /nodes/{node}/qemu is the only way

Proxmox API create VM cluster not per node — that’s the thing people keep asking. The API has no cluster-wide VM creation endpoint. VMs live on nodes, so you POST to /nodes/{node}/qemu. That’s the whole answer, but the confusion comes from expecting the cluster to act like one big hypervisor.

The API model: cluster is a view, not a hypervisor

Proxmox clusters are a control plane. They share configs, migrate VMs, and manage storage. But a VM always runs on a specific node. The API mirrors that. Look at the endpoints: /cluster/nextid gives you a free VMID from the cluster’s range. /nodes/{node}/qemu creates the VM on that node. There is no /cluster/qemu.

If you want to create a VM “on the cluster”, you still have to pick a node. The cluster API helps you pick a good one, but the create call is node-scoped. That’s not a missing feature; it’s how Proxmox is built.

How to do it without pulling your hair out

First, get a VMID from the cluster. This is the part people skip, then they hardcode an ID and hit a conflict.

curl -s -k -H 'Authorization: PVEAPIToken=USER@REALM!TOKEN=UUID' \
  https://your-cluster-ip:8006/api2/json/cluster/nextid

That returns something like {“data”:”100″}. Now create the VM on a node. You need a node name — get one from /nodes if you don’t have a preference.

curl -s -k -X POST -H 'Authorization: PVEAPIToken=USER@REALM!TOKEN=UUID' \
  --data-urlencode 'vmid=100' \
  --data-urlencode 'name=test-vm' \
  --data-urlencode 'memory=512' \
  --data-urlencode 'cores=1' \
  --data-urlencode 'net0=virtio,bridge=vmbr0' \
  https://your-cluster-ip:8006/api2/json/nodes/pve1/qemu

That’s it. The VM is created on pve1. If you want it elsewhere, change the node in the URL. The cluster doesn’t decide for you.

Why not just add a cluster endpoint?

Because then the API would have to pick a node, and that’s a policy decision. Proxmox leaves it to you. There’s a pvesh recipe for exporting summaries that shows the same node/cluster split — cluster endpoints for cluster stuff, node endpoints for node stuff. Keep that mental model and the API stops feeling weird.

If you’re scripting a lot of VM creation, write a wrapper that calls /cluster/nextid, then POSTs to the node you want. Don’t fight the API; use the two-step flow. It’s less code than trying to make a cluster endpoint exist.