The Proxmox VE API from JavaScript

By developers, for developers.

Built by Corsinvest, official Proxmox partner.

npm

npm install @corsinvest/cv4pve-api-javascript

Yarn

yarn add @corsinvest/cv4pve-api-javascript

pnpm

pnpm add @corsinvest/cv4pve-api-javascript

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-javascript 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 the JSDoc of each method carries the same descriptions.

const { PveClient } = require("@corsinvest/cv4pve-api-javascript");

const client = new PveClient("pve01");
client.apiToken = "automation@pve!app=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";

// GET /nodes/{node}/qemu/{vmid}/status/current
const result = await client.nodes.get("pve01").qemu.get(100).status.current.vmStatus();

console.log(
  result.isSuccessStatusCode
    ? `VM ${result.response.data.vmid} is ${result.response.data.status}`
    : `${result.statusCode} ${result.reasonPhrase}`
);

From endpoint to methodPaths become properties and get(...), the methods of an endpoint become JavaScript methods, parameters become arguments.

In your application, API only

The client runs where Node.js 18 or later 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 the JavaScript way into the same API the tools of the suite use. If a ready tool already does the job, use the tool: cv4pve-cli calls the API from any shell, cv4pve-autosnap takes snapshots with retention. The same client exists for .NET with cv4pve-api-dotnet, for Java with cv4pve-api-java, for PHP with cv4pve-api-php and for 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 answer together, as plain JavaScript objects. An answer with an error status does not throw.

API token or password

Connect with an API token or a user and password, with two-factor authentication, certificate validation and timeout.

Tasks

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

Raw calls

GET, POST, PUT and DELETE on any path with an object of parameters: for the calls with many options and for endpoints newer than the library.

Promises and typings

Every call returns a promise, for async and await. The TypeScript typings are in the package. One small dependency.

Part of the cv4pve suite →

Write your first call

Install the package from npm, connect to any node, read your VMs.

Made by Corsinvest,
official Proxmox partner

Get startedProfessional support