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.
@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/sdkIt 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 cancelledOptions
| Option | Default | Description |
|---|---|---|
baseUrl | VAULTPANEL_URL | The panel's address, with or without /api/v1 and a trailing slash. https:// is added when no scheme is given. |
token | VAULTPANEL_TOKEN | An API token, or a plugin's vpp_ token. Sent as Authorization: Bearer. |
timeoutMs | 30000 | Per request. |
retries | 2 | Retries 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. |
userAgent | vaultpanel-sdk | |
fetch | globalThis.fetch | Your own fetch, for tests or proxies. |
onRequest | Called 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
| Resource | Methods |
|---|---|
panel.servers | list(query), get(id), create(body), update(id, body), remove(id), metrics(id, query), enrollmentToken(id), updateAgent(id), runOperation(id, body) |
panel.servers.groups | list(), get(id), create(body), update(id, body), remove(id) |
panel.bulkActions | list(query), get(id), create(body), cancel(id) |
panel.websites | list(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.domains | list(query) |
panel.subdomains | parents(), create(body) |
panel.certificates | list(query) |
panel.dns | zones(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.mail | servers(), 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.cms | catalog(), installs(query), install(body), get(id), remove(id, query) |
panel.applications | list(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.deployments | list(query), get(id) |
panel.databases | list(query), get(id), create(body), update(id, body), remove(id) |
panel.databases.users | list(query), create(body), update(id, body), remove(id), password(id) |
panel.containers | list(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.onServer | docker(serverId), installDocker(serverId), list(serverId), logs(serverId, ref, body), inspect(serverId, ref), act(serverId, ref, action), images(serverId), pullImage(serverId, body) |
panel.backups | list(query), get(id), create(body), remove(id), restore(id, body) |
panel.backups.storage | list(), get(id), create(body), update(id, body), remove(id), test(id, body) |
panel.backups.schedules | list(query), save(body), remove(id) |
panel.cronJobs | list(query), get(id), create(body), update(id, body), remove(id), run(id), runs(id, query) |
panel.webhooks | list(query), get(id), create(body), update(id, body), remove(id), test(id), deliveries(id, query) |
panel.alerts | summary(), events(query), acknowledge(id), rules(), createRule(body), updateRule(id, body), removeRule(id) |
panel.monitoring | overview(), services(query) |
panel.security | overview(), server(serverId), setFirewall(serverId, body), addFirewallRule(serverId, body), removeFirewallRule(serverId, body), installUpdates(serverId) |
panel.jobs | list(query), get(id, query), operations(), cancel(id), wait(id, options) |
panel.users | list(query), get(id), invite(body), update(id, body), roles() |
panel.auditLog | list(query) |
panel.apiTokens | list(query), scopes(), create(body), revoke(id) |
panel.hosting | plans(), 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.plugins | list(), get(id), pages(), preview(body), enable(id), disable(id), remove(id), deliveries(id, query), test(id), directory(), refreshDirectories(), refreshDirectory(directoryId), removeDirectory(directoryId) |
panel | me(), 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
}
}code | Meaning |
|---|---|
| The panel's own code | Such as NOT_FOUND, FORBIDDEN, QUOTA_REACHED. See errors. |
NETWORK | The panel could not be reached. |
TIMEOUT | The panel did not answer within timeoutMs. |
BAD_RESPONSE | Something that is not the API answered, usually the wrong URL. |
JOB_WAIT_TIMEOUT | jobs.wait gave up before the job finished. |
CONFIG | A 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:
| Function | Returns |
|---|---|
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.
Plugins
Extend VaultPanel with plugins — separate programs that call the API with their own token, receive signed events and add a page to the panel's sidebar.
Development
Run VaultPanel from source for development — MariaDB and Redis in Docker, the API, worker and interface in watch mode, the checks CI runs and the code conventions.