# JavaScript SDK

URL: https://docs.vaultpanel.net/developers/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](https://docs.vaultpanel.net/api-reference): one small class over `fetch`, with no dependencies and a method for each thing the panel manages. The [CLI](https://docs.vaultpanel.net/cli) is built on it. It is MIT licensed.

## Install

```bash
npm install @vaultpanel/sdk
```

It needs Node.js 22 or newer and an [API token](https://docs.vaultpanel.net/api-reference/api-tokens), 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

```js
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

| 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:

```js
// 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](https://docs.vaultpanel.net/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:

```js
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.

```js
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:

```js
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](https://docs.vaultpanel.net/api-reference). |
| `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](https://docs.vaultpanel.net/developers/plugins) 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.
