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 getter: /cluster/resources is client.getCluster().getResources().
2. Each {value} of the path is a get(value): /nodes/{node}/qemu/{vmid} is client.getNodes().get("pve01").getQemu().get(100).
3. Each HTTP method of the endpoint is a Java method named after the API method, with its parameters as arguments.

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

Containers are the same under getLxc() instead of getQemu().

All of them return 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. In practice type the path and let the editor list what the endpoint offers: the Javadoc of each method carries the description of the API, and of each parameter.

var vm = client.getNodes().get("pve01").getQemu().get(100);

var config = vm.getConfig().vmConfig();                 // GET
var start = vm.getStatus().getStart().vmStart();        // POST
var stop = vm.getStatus().getShutdown().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

Java has no named arguments, so each method of the API exists in two forms: one with only the required parameters, and one with all of them, in the order of the Javadoc. A parameter passed as null is not sent, so Proxmox VE applies its own default.

// required parameters only
var snapshot = vm.getSnapshot().snapshot("before-update");

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

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

• Names are those of the API. A - in a name becomes _: force-cpu is force_cpu.
• Required parameters have primitive types (int, boolean), the optional ones the wrapper types (Integer, Boolean), so that they can be null. Booleans are sent as 1 or 0.
• Parameters that exist with an index (net0, net1, scsi0) are one Map<Integer, String> argument, netN, scsiN: 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

With many parameters of the same type, a value in the wrong position compiles and 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.

Raw calls

The generated methods end in four methods of the client, which you can call with any path and a map 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:

import java.util.HashMap;

var parameters = new HashMap<String, Object>();
parameters.put("cores", 4);
parameters.put("memory", 8192);
parameters.put("description", "Web server");

var update = client.set("/nodes/pve01/qemu/100/config", parameters);

var read = client.get("/nodes/pve01/qemu/100/config", null);

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. For GET and DELETE the parameters go in the query string, for POST and PUT in a JSON body. The map can be null when there are none. They return 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.