Getting started

cv4pve-api-dotnet is a set of NuGet packages. The main one, Corsinvest.ProxmoxVE.Api, is 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

• .NET 8, 9 or 10.
• 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 package from NuGet:

   dotnet add package Corsinvest.ProxmoxVE.Api

2. Create the client

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

   using Corsinvest.ProxmoxVE.Api;
   
   var client = new PveClient("pve01")
   {
       ApiToken = "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 = await client.Version.Version();
   
   if (result.IsSuccessStatusCode)
   {
       Console.WriteLine($"Proxmox VE {result.Response.data.version}");
   }
   else
   {
       Console.WriteLine($"{(int)result.StatusCode} {result.ReasonPhrase}");
   }

4. Read some data

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

   // GET /nodes/{node}/qemu/{vmid}/status/current
   var current = await client.Nodes["pve01"].Qemu[100].Status.Current.VmStatus();
   Console.WriteLine(current.Response.data.status);
   
   // GET /cluster/resources?type=vm
   var resources = await client.Cluster.Resources.Resources(type: "vm");
   foreach (var item in resources.ToEnumerable())
   {
       Console.WriteLine($"{item.vmid} {item.node} {item.status}");
   }

Every call returns a Result: the HTTP outcome and, in Response.data, 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 property, each {value} in the path is an indexer, and each HTTP method of the endpoint is a C# method. The Proxmox VE API viewer is therefore the reference for parameters and returned data, and IntelliSense shows the same descriptions while you type. The rule is in API structure.

The other packages

Package	Adds
Corsinvest.ProxmoxVE.Api.Extension	Typed helpers: VMs and containers by id, name or pattern, snapshots, status, cluster resources
Corsinvest.ProxmoxVE.Api.Shared	The typed models of the Proxmox VE data
Corsinvest.ProxmoxVE.Api.Console	Helpers to build a command line tool: login options, client from the command line
Corsinvest.ProxmoxVE.Api.Metadata	The schema of the Proxmox VE API as objects

Next

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