Getting started

cv4pve-api-java is one library on Maven Central: a client with a method for every endpoint of the Proxmox VE API. It runs in your application (a service, a scheduled job, a command line tool) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes.

Requirements

• Java 17 or later.
• Network access to port 8006 of at least one node.
• A Proxmox VE API token, or a user and password, with the privileges your application needs: see Permissions.

Install

1. Add the package

   Add the dependency from Maven Central:

   Maven

   <dependency>
       <groupId>it.corsinvest.proxmoxve</groupId>
       <artifactId>cv4pve-api-java</artifactId>
       <version>9.2.3</version>
   </dependency>

   Gradle

   implementation 'it.corsinvest.proxmoxve:cv4pve-api-java:9.2.3'

   The only dependency it brings is Jackson, used for JSON.

2. Create the client

   Create the client with an API token. With a token there is no login call:

   import it.corsinvest.proxmoxve.api.PveClient;
   
   var client = new PveClient("pve01", 8006);
   client.setApiToken("automation@pve!app=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");

   The certificate of the node is not validated unless you ask for it, so a new installation with its self-signed certificate works as it is. All the ways to connect are in Connection.

3. Make the first call

   Make the first call and check its outcome:

   var result = client.getVersion().version();
   
   if (result.isSuccessStatusCode()) {
       System.out.println("Proxmox VE " + result.getData().get("version").asText());
   } else {
       System.out.println(result.getStatusCode() + " " + result.getReasonPhrase());
   }

4. Read some data

   Read some data. The path of the API is the path in the code:

   import com.fasterxml.jackson.databind.JsonNode;
   
   // GET /nodes/{node}/qemu/{vmid}/status/current
   var current = client.getNodes().get("pve01").getQemu().get(100).getStatus().getCurrent().vmStatus();
   System.out.println(current.getData().get("status").asText());
   
   // GET /cluster/resources?type=vm
   var resources = client.getCluster().getResources().resources("vm");
   for (JsonNode item : resources.getData()) {
       System.out.println(item.get("vmid").asInt() + " " + item.get("node").asText() + " "
               + item.get("status").asText());
   }

Every call returns a Result: the HTTP outcome and, in getData(), what Proxmox VE answered. A failed call does not throw, so check isSuccessStatusCode(): Results and Errors explain why.

Find the method you need

The client follows the tree of the Proxmox VE API: each part of a path is a getter, each {value} in the path is a get(value), and each HTTP method of the endpoint is a Java method. The Proxmox VE API viewer is therefore the reference for parameters and returned data, and the Javadoc shows the same descriptions in your editor. The rule is in API structure.

Next

• Connection: API token or password, two-factor authentication, certificates, timeout, proxy.
• Permissions: the user, the token and the privileges an application needs.
• Concepts: API structure, results, tasks, errors.
• Common tasks: short recipes to copy.