API Reference

API overview

The VaultPanel REST API at a glance, covering base URL, authentication, the response envelope, errors, pagination, rate limits and background jobs.

Last updated

Everything the panel's interface does goes through one JSON REST API, and so do the command-line tool, the JavaScript SDK and plugins. This page covers the conventions every endpoint shares. The pages in this section document each endpoint.

Base URL

https://panel.example.com/api/v1

Use the address you open the panel at: its domain when it has one, or https://203.0.113.10:8090 on a new install. There is one version of the API, v1, in the path.

Quick start

Create an API token

In the panel, open Users & Access > API Tokens and create a token with the scopes your script needs. The token (vpt_…) is shown once. See API tokens.

Call the API

export VAULTPANEL_TOKEN=vpt_…
curl https://panel.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
import { VaultPanel } from '@vaultpanel/sdk';

const panel = new VaultPanel({
  baseUrl: 'https://panel.example.com',
  token: process.env.VAULTPANEL_TOKEN,
});

const me = await panel.me();
console.log(me.user.email, me.apiToken.scopes);

The JavaScript examples in this reference use the panel client above. SDK methods return the envelope's data and throw a VaultPanelError (with status, code, details and requestId) for every error. See JavaScript SDK.

Authentication

CallerCredentialWhere
Scripts, the CLI and the SDKAuthorization: Bearer vpt_… (an API token)Every endpoint except most of /auth
The panel in a browserThe vp_session cookie, plus X-CSRF-Token on changesEvery endpoint
PluginsAuthorization: Bearer vpp_… (the plugin's own token)What the owner approved
Billing systemsvpk_… billing API keys/billing only
Server agentsEd25519-signed requests/agent only
Git hostsA secret token in the URL, plus a signature/hooks/deploy/:token only

A token acts as the person who created it, narrowed to its scopes, and every call it makes is in the audit log under that person. See Authentication.

Each endpoint in this reference names the permission the panel checks and the token scope that grants it. A request without the permission answers 403 FORBIDDEN, and the denial is written to the audit log.

Requests

  • Send JSON with Content-Type: application/json. Bodies are limited to 4 MB (the file upload endpoint, which takes raw bytes, is the exception).
  • IDs are UUIDs. Timestamps are ISO 8601 strings in UTC.
  • Query parameters are strings and are converted where the endpoint expects numbers or booleans (true or false).

The response envelope

Every response, success or error, has the same shape:

200 OK
{
  "success": true,
  "data": { "status": "ok" },
  "message": "OK",
  "requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10"
}
422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are invalid",
    "details": [{ "field": "email", "message": "Enter a valid email address" }]
  },
  "requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10"
}

message is a human-readable summary of what happened, such as Website saved. The agent is creating it on the server.

Request IDs

Every response carries a request id in requestId and in the X-Request-Id header. It also appears in the panel's logs and in the audit log. Send your own X-Request-Id (8 to 64 letters, digits, ., _ or -) and the panel uses it instead of generating one. Quote the request id when you report a problem.

Errors

Errors carry a stable machine-readable code. Branch on the code, not on the message.

StatusCodeMeaning
400BAD_REQUESTThe request cannot be carried out as sent.
400BAD_JSONThe body is not valid JSON.
401UNAUTHENTICATEDNo valid session or token. A revoked or expired token also answers this.
403FORBIDDENSigned in, but without the permission (or CSRF token) this needs.
403IP_NOT_ALLOWEDThe panel only accepts approved addresses, and yours is not one.
403TWO_FACTOR_SETUP_REQUIREDYour account must turn on two-factor sign-in before it can use anything but /auth.
404NOT_FOUNDNo such record, or one you cannot see. Unknown routes also answer this.
409CONFLICT and specific codesThe current state does not allow it. Most 409s have their own code, such as WEBSITE_BUSY or AGENT_OUTDATED.
413PAYLOAD_TOO_LARGEThe body is over the size limit.
422VALIDATION_ERROROne or more fields are invalid. details lists them.
429RATE_LIMITEDToo many requests.
500INTERNAL_ERRORSomething failed on the panel. The message never contains internals.
503DEGRADEDOnly from GET /health, when the database or Redis is down.

Validation errors

details lists one entry per problem. field is the path of the field, with dots for nested fields and array positions (env.2.key, params.service).

{
  "code": "VALIDATION_ERROR",
  "message": "Some fields are invalid",
  "details": [
    { "field": "name", "message": "Use 3 to 32 lowercase letters, digits and dashes, starting with a letter" },
    { "field": "domains", "message": "Add at least one domain" }
  ]
}

Some 409 errors carry details too, such as the jobId of the job that is already running.

Lists and pagination

List endpoints share these query parameters:

NameTypeDefaultDescription
pageinteger1Page number, from 1.
pageSizeinteger25Items per page, 1 to 100.
sortstringper endpointA column the endpoint allows, such as createdAt or name.
orderstringper endpointasc or desc.

Endpoints add their own filters (search, serverId, status and so on). Lists answer with:

{
  "items": [],
  "pagination": { "page": 1, "pageSize": 25, "total": 0, "totalPages": 1 }
}

The SDK walks every page for you:

for await (const site of panel.paginate('/websites', { serverId })) {
  console.log(site.primaryDomain);
}

Rate limits

Limits apply per client IP address, in each panel process. A limited request answers 429 RATE_LIMITED. Responses carry the RateLimit-Policy and RateLimit headers (IETF draft 8), so a client can see how much is left.

Applies toLimit
Every endpoint under /api/v1 except /health, /agent, /hooks and /billing600 requests a minute
Sign-in, the second sign-in step, single sign-on, password changes and two-factor changes20 requests in 15 minutes
POST /auth/setup10 requests in 15 minutes
Password reset requests and links20 requests in 15 minutes
POST /hooks/deploy/:token30 requests a minute
/billing120 requests a minute
Agent registration30 requests an hour
Agent install script and package downloads60 requests a minute

The SDK retries GET requests answered with 429, 502, 503 or 504 twice, with backoff.

Jobs: the asynchronous model

Anything that changes a server (creating a website, deploying an app, restarting a service) is carried out by the agent on that server. The API saves the request, queues a job and answers 202 Accepted with the job. The record the job acts on shows what is running in its status and pendingAction, and keeps its current settings until the job succeeds.

202 Accepted
{
  "success": true,
  "data": {
    "website": { "id": "0b8e…", "status": "creating", "pendingAction": "create" },
    "job": { "id": "a1d3…", "type": "CREATE_SITE", "status": "queued" }
  },
  "message": "Website saved. The agent is creating it on the server.",
  "requestId": "…"
}

Follow the job with GET /api/v1/jobs/:id until its status is succeeded, failed, timed_out or cancelled. The SDK does this for you:

const { job } = await panel.applications.deploy(appId);
const { job: done, logs } = await panel.jobs.wait(job.id); // throws if it does not finish in time

Reads that need the server, such as file listings and log lines, are jobs too. Their result arrives in the job's output. See Jobs.

Health

GET/api/v1/health
Auth
None

Whether the panel can reach its database and Redis. No authentication and no rate limit, for load balancers and uptime checks.

curl https://panel.example.com/api/v1/health
200 OK
{ "success": true, "data": { "status": "ok", "checks": { "database": "ok", "redis": "ok" } }, "message": "OK", "requestId": "…" }

When either is down it answers 503 with code DEGRADED, and details holds the same checks object (ok or unavailable for each).

Hosting customers

A hosting customer signs in to the same API. They reach only their own websites, subdomains, domains, certificates, apps, deployments, databases, backups, cron jobs and jobs, and the /auth, /api-tokens and /hosting areas. Every other area answers 403 FORBIDDEN, and a record of another account answers 404 NOT_FOUND. Creating something beyond their plan answers 409 QUOTA_REACHED. See Hosting and billing.

Endpoint reference