JavaScript SDK

Use @vaultpanel/sdk to call the VaultPanel REST API from Node.js — client options, every resource method, pagination, waiting for jobs and error handling.

Last updated

@vaultpanel/sdk is the JavaScript client for the REST API: one small class over fetch, with no dependencies and a method for each thing the panel manages. The CLI is built on it. It is MIT licensed.

Install

npm install @vaultpanel/sdk

It needs Node.js 22 or newer and an API token, created under Users & Access > API Tokens. The token acts as the person who made it, narrowed to its scopes, so the SDK can never do more than that person can.

Quick start

import { VaultPanel } from '@vaultpanel/sdk';

const panel = new VaultPanel({
  baseUrl: 'https://panel.example.com', // or VAULTPANEL_URL
  token: process.env.VAULTPANEL_TOKEN,  // an API token (vpt_…)
});

const { items } = await panel.servers.list();
const { job } = await panel.applications.deploy(appId);
const { job: done } = await panel.jobs.wait(job.id);
console.log(done.status); // succeeded, failed, timed_out or cancelled

Options

OptionDefaultDescription
baseUrlVAULTPANEL_URLThe panel's address, with or without /api/v1 and a trailing slash. https:// is added when no scheme is given.
tokenVAULTPANEL_TOKENAn API token, or a plugin's vpp_ token. Sent as Authorization: Bearer.
timeoutMs30000Per request.
retries2Retries for GET requests on 429, 502, 503 and 504, network errors and timeouts, with backoff (honouring retryAfterSeconds when the panel sends it). Other methods are never retried.
userAgentvaultpanel-sdk
fetchglobalThis.fetchYour own fetch, for tests or proxies.
onRequestCalled with { method, url } before each request.

The environment defaults apply only where there is an environment (Node.js, Deno, Bun); in a browser, pass both.

isApiToken(value) checks that a string looks like an API token before any call, catching a pasted password or a truncated copy.

Return values

Every method returns the data of the reply envelope. For anything not wrapped, or to get the message and request id:

// Any endpoint (paths are relative to /api/v1).
await panel.request('POST', `/servers/${id}/jobs`, { body: { type: 'SERVICE_RESTART', params: { service: 'nginx' } } });

// The whole envelope: { success, data, message, requestId }
const envelope = await panel.raw('GET', '/websites');

request(method, path, options) takes query, body, headers, timeoutMs and idempotent (allow retries for a non-GET call).

Resources

ResourceMethods
panel.serverslist(query), get(id), create(body), update(id, body), remove(id), metrics(id, query), enrollmentToken(id), updateAgent(id), runOperation(id, body)
panel.servers.groupslist(), get(id), create(body), update(id, body), remove(id)
panel.bulkActionslist(query), get(id), create(body), cancel(id)
panel.websiteslist(query), get(id), create(body), update(id, body), remove(id, query), enable(id), disable(id), retry(id), issueSsl(id, body), renewSsl(id, body), disableSsl(id), logs(id, body), checkDns(id), files(id, action, body)
panel.domainslist(query)
panel.subdomainsparents(), create(body)
panel.certificateslist(query)
panel.dnszones(query), zone(id), createZone(body), updateZone(id, body), removeZone(id), apply(id), check(id), addRecord(zoneId, body), updateRecord(zoneId, recordId, body), removeRecord(zoneId, recordId)
panel.mailservers(), setupServer(body), domains(query), domain(id), createDomain(body), removeDomain(id, query), checkDns(id), createMailbox(domainId, body), updateMailbox(domainId, id, body), removeMailbox(domainId, id, query), createForwarder(domainId, body), removeForwarder(domainId, id)
panel.cmscatalog(), installs(query), install(body), get(id), remove(id, query)
panel.applicationslist(query), get(id), create(body), update(id, body), remove(id, query), environment(id), setEnvironment(id, body), deploy(id), rollback(id, body), apply(id), scale(id, instances), refreshStatus(id), logs(id, body), start(id), stop(id), restart(id)
panel.deploymentslist(query), get(id)
panel.databaseslist(query), get(id), create(body), update(id, body), remove(id)
panel.databases.userslist(query), create(body), update(id, body), remove(id), password(id)
panel.containerslist(query), get(id), create(body), update(id, body), remove(id, query), environment(id), redeploy(id, body), start(id), stop(id), restart(id), servers()
panel.containers.onServerdocker(serverId), installDocker(serverId), list(serverId), logs(serverId, ref, body), inspect(serverId, ref), act(serverId, ref, action), images(serverId), pullImage(serverId, body)
panel.backupslist(query), get(id), create(body), remove(id), restore(id, body)
panel.backups.storagelist(), get(id), create(body), update(id, body), remove(id), test(id, body)
panel.backups.scheduleslist(query), save(body), remove(id)
panel.cronJobslist(query), get(id), create(body), update(id, body), remove(id), run(id), runs(id, query)
panel.webhookslist(query), get(id), create(body), update(id, body), remove(id), test(id), deliveries(id, query)
panel.alertssummary(), events(query), acknowledge(id), rules(), createRule(body), updateRule(id, body), removeRule(id)
panel.monitoringoverview(), services(query)
panel.securityoverview(), server(serverId), setFirewall(serverId, body), addFirewallRule(serverId, body), removeFirewallRule(serverId, body), installUpdates(serverId)
panel.jobslist(query), get(id, query), operations(), cancel(id), wait(id, options)
panel.userslist(query), get(id), invite(body), update(id, body), roles()
panel.auditLoglist(query)
panel.apiTokenslist(query), scopes(), create(body), revoke(id)
panel.hostingplans(), createPlan(body), updatePlan(id, body), removePlan(id), customers(query), customer(id), createCustomer(body), updateCustomer(id, body), changePlan(id, planId), suspend(id, reason), unsuspend(id), terminate(id), me()
panel.pluginslist(), get(id), pages(), preview(body), enable(id), disable(id), remove(id), deliveries(id, query), test(id), directory(), refreshDirectories(), refreshDirectory(directoryId), removeDirectory(directoryId)
panelme(), dashboard(), health(), request(), raw(), paginate(), listAll(), waitForJob()

Request bodies and query parameters are those of the matching endpoint in the API reference. Creating API tokens, installing plugins and adding plugin directories are refused for tokens: they are done in the panel while signed in.

Lists

List endpoints return { items, pagination }, with page, pageSize (up to 100), sort, order and per-endpoint filters. To walk every page:

for await (const site of panel.paginate('/websites', { pageSize: 50 })) {
  console.log(site.name);
}

const servers = await panel.listAll('/servers');

Jobs

Long operations (deployments, website changes, backups) answer with a job, and the real outcome arrives later. jobs.wait polls until the job reaches a final state and returns { job, logs }. It throws JOB_WAIT_TIMEOUT rather than letting a script carry on as if the work had succeeded; it does not throw when the job itself failed, so check the status.

const { job, logs } = await panel.jobs.wait(id, {
  timeoutMs: 600_000, // default 10 minutes
  intervalMs: 2_000,  // default 2 seconds
  onProgress: (job, lines) => lines.forEach((line) => console.log(line.message)),
});
if (job.status !== 'succeeded') throw new Error(job.error ?? job.status);

jobs.wait also accepts a reply that contains a job, such as { job }.

Errors

Every failure throws a VaultPanelError carrying what the panel said:

import { VaultPanelError } from '@vaultpanel/sdk';

try {
  await panel.websites.create({ name: '', serverId });
} catch (err) {
  if (err instanceof VaultPanelError) {
    err.status;            // 422
    err.code;              // 'VALIDATION_ERROR'
    err.fieldErrors;       // { name: 'Required' }
    err.details;           // the error's details, as the panel sent them
    err.requestId;         // quote this when reporting a problem
    err.isAuthError;       // 401 or 403: the token is gone, or its scopes are too narrow
    err.isValidationError; // 422
  }
}
codeMeaning
The panel's own codeSuch as NOT_FOUND, FORBIDDEN, QUOTA_REACHED. See errors.
NETWORKThe panel could not be reached.
TIMEOUTThe panel did not answer within timeoutMs.
BAD_RESPONSESomething that is not the API answered, usually the wrong URL.
JOB_WAIT_TIMEOUTjobs.wait gave up before the job finished.
CONFIGA missing baseUrl, no fetch, or nothing to wait for.

For plugin authors

A plugin calls the API with new VaultPanel({ token: 'vpp_…' }), and checks what the panel signs with two helpers:

FunctionReturns
verifyEvent({ body, headers, secret, toleranceSeconds })The event { id, event, occurredAt, data }, or null. Pass the raw body.
verifyLaunch(url, secret, { maxAgeSeconds }){ plugin, user: { id, email, roles }, panelUrl, theme, issuedAt }, or null.
launchSigningString(params)The string the panel signs for a page link.

Both checks run in constant time and refuse signatures older than 5 minutes.