The Proxmox VE API from .NET

By developers, for developers.

Built by Corsinvest, official Proxmox partner.

# add the client to your project
dotnet add package Corsinvest.ProxmoxVE.Api

# helpers for VMs, containers and tasks
dotnet add package Corsinvest.ProxmoxVE.Api.Extension

Why

An application that manages Proxmox VE (a customer portal, a scheduled job, a monitoring or billing tool) has to speak its REST API: tickets and tokens, paths, parameters, JSON, tasks that end later. Written by hand it is a layer of HTTP code to build and to keep up with every Proxmox VE release.

cv4pve-api-dotnet is that layer, generated from the API itself. The calls follow the tree of the API, so the Proxmox VE API viewer is also the reference of the client, and IntelliSense shows the same descriptions while you type.

using Corsinvest.ProxmoxVE.Api;

var client = new PveClient("pve01")
{
    ApiToken = "automation@pve!app=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
};

// GET /nodes/{node}/qemu/{vmid}/status/current
var result = await client.Nodes["pve01"].Qemu[100].Status.Current.VmStatus();

Console.WriteLine(result.IsSuccessStatusCode
                    ? $"VM {result.Response.data.vmid} is {result.Response.data.status}"
                    : $"{(int)result.StatusCode} {result.ReasonPhrase}");

From endpoint to methodPaths become properties and indexers, the methods of an endpoint become C# methods, parameters become arguments.

In your application, API only

The client runs where .NET 8, 9 or 10 runs (Windows, Linux, macOS, a container, a CI runner) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes and no SSH is needed. What an application can do is what its API token or user is allowed to do: give it a token with just the privileges it needs, see Permissions.

Where it fits

The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. This library is what the .NET tools of the suite are built on, among them cv4pve-cli, cv4pve-autosnap, cv4pve-diag and cv4pve-report: use it to build your own. If a ready tool already does the job, use the tool. For scripts rather than applications, the same API is available from PowerShell with cv4pve-api-powershell.

What it does for you

The whole API

A method for every endpoint and HTTP method, generated from the Proxmox VE API schema, placed where the API has it: the path of an endpoint is the path in the code.

One Result for every call

The HTTP outcome and the Proxmox VE data together: read it as dynamic, as a dictionary or as a typed model. A failed call does not throw.

API token or password

Connect with an API token or a user and password, with two-factor authentication, OpenID, your own HttpClient, and a list of nodes to try.

Tasks

Start a backup, a clone or a migration, wait for its task to finish and read whether it succeeded.

VMs by id, name or pattern

The Extension package finds VMs and containers without knowing their node, by id, name, range, pool or tag, and reads the data as typed models.

Command line tools

The Console package gives a tool the connection options, the logging and the behaviour of the cv4pve suite.

Part of the cv4pve suite →

Write your first call

Add the package from NuGet, connect to any node, read your VMs.

Made by Corsinvest,
official Proxmox partner

Get startedProfessional support