API structure

PveClient is generated from the schema of the Proxmox VE API, the same one the API viewer shows. It has a method for each method of the API, placed where the API has it. Knowing the path of an endpoint is enough to write the call.

From endpoint to method

Three rules:

1. Each fixed part of the path is a property: /cluster/resources is client.cluster.resources. A - or a _ in the name is dropped and the next letter is upper case: /cluster/backup-info is client.cluster.backupInfo.
2. Each {value} of the path is a get(value): /nodes/{node}/qemu/{vmid} is client.nodes.get("pve01").qemu.get(100).
3. Each HTTP method of the endpoint is a JavaScript method named after the API method, with its parameters as arguments. It returns a promise.

Endpoint	Call
GET /version	client.version.version()
GET /cluster/resources	client.cluster.resources.resources("vm")
GET /nodes	client.nodes.index()
GET /nodes/{node}/qemu	client.nodes.get("pve01").qemu.vmlist()
POST /nodes/{node}/qemu	client.nodes.get("pve01").qemu.createVm(100)
GET /nodes/{node}/qemu/{vmid}/config	client.nodes.get("pve01").qemu.get(100).config.vmConfig()
GET /nodes/{node}/qemu/{vmid}/status/current	client.nodes.get("pve01").qemu.get(100).status.current.vmStatus()
POST /nodes/{node}/qemu/{vmid}/status/start	client.nodes.get("pve01").qemu.get(100).status.start.vmStart()
GET /nodes/{node}/qemu/{vmid}/snapshot	client.nodes.get("pve01").qemu.get(100).snapshot.snapshotList()
POST /nodes/{node}/qemu/{vmid}/snapshot	client.nodes.get("pve01").qemu.get(100).snapshot.snapshot("before-update")
DELETE /nodes/{node}/qemu/{vmid}/snapshot/{snapname}	client.nodes.get("pve01").qemu.get(100).snapshot.get("before-update").delsnapshot()
DELETE /nodes/{node}/qemu/{vmid}	client.nodes.get("pve01").qemu.get(100).destroyVm()

Containers are the same under lxc instead of qemu.

All of them resolve with a Result: see Results.

Method names

The name of a method is the name Proxmox VE gives to that API method, in camel case: vm_config becomes vmConfig, snapshot_list becomes snapshotList. Lists are often called index, the others have names of their own, so there is no fixed name per HTTP method. A name that is a reserved word of JavaScript ends with _: delete_(). In practice type the path and let the editor list what the endpoint offers: the JSDoc of each method carries the description of the API, and of each parameter.

const vm = client.nodes.get("pve01").qemu.get(100);

const config = await vm.config.vmConfig();            // GET
const start = await vm.status.start.vmStart();        // POST
const stop = await vm.status.shutdown.vmShutdown();   // POST

Note

A node of the tree can be kept in a variable, as vm above: it holds only the path, no call is made until a method is called.

Parameters

The parameters of a method are positional arguments: the required ones first, then the optional ones, in the order of the JSDoc. A parameter left out, or passed as undefined or null, is not sent, so Proxmox VE applies its own default.

// required parameters only
let snapshot = await vm.snapshot.snapshot("before-update");

// every parameter: snapname, description, vmstate
snapshot = await vm.snapshot.snapshot("before-update", "Before the update", true);

// undefined for the ones to leave out
snapshot = await vm.snapshot.snapshot("before-update", undefined, true);

• Names are those of the API. A - in a name becomes _: force-cpu is force_cpu. A name that is a reserved word ends with _: delete is delete_, protected is protected_.
• Booleans are sent as 1 or 0.
• Parameters that exist with an index (net0, net1, scsi0) are one object argument, netN, scsiN, with the index as key: see Indexed parameters.
• Type, format and allowed values of each parameter are in the API viewer; the client sends what you give and Proxmox VE validates it. A refused parameter gives status 400: see Errors.

Caution

The arguments are matched by position, not by name: an object such as updateVm({ memory: 4096 }) is taken as the value of the first parameter. With many parameters, a value in the wrong position is sent under the wrong name. Some methods have about a hundred parameters: the configuration of a VM (createVm, updateVm) is the main case. For those, use a raw call, where each value has its name.

The position of a parameter can change from a version of the library to the next, when Proxmox VE adds parameters to an endpoint: these changes are listed in the changelog under “Changed (breaking)”. A raw call does not depend on positions.

Raw calls

The generated methods end in four methods of the client, which you can call with any path and an object of parameters. They are the practical way for the calls with many optional parameters, for an endpoint added by a Proxmox VE version newer than the library, and when the path is built at run time:

const update = await client.set("/nodes/pve01/qemu/100/config", {
  cores: 4,
  memory: 8192,
  description: "Web server",
});

const read = await client.get("/nodes/pve01/qemu/100/config");

Method	HTTP
get(resource, parameters)	GET
create(resource, parameters)	POST
set(resource, parameters)	PUT
delete(resource, parameters)	DELETE

Here the parameter names are exactly those of the API, with - where the API has it: quote them, { "force-cpu": "host" }. For GET and DELETE the parameters go in the query string, for POST and PUT in a JSON body. The object can be left out when there are none. They resolve with the same Result as the generated methods.

Versions

The first two numbers of the library version are the Proxmox VE version it was generated from: 9.2.x matches the API of Proxmox VE 9.2. A library newer than the cluster may offer endpoints and parameters the cluster does not know: the cluster answers an unknown endpoint with status 501 and an unknown parameter with status 400.