API overview
The VaultPanel REST API at a glance, covering base URL, authentication, the response envelope, errors, pagination, rate limits and background jobs.
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/v1Use 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
| Caller | Credential | Where |
|---|---|---|
| Scripts, the CLI and the SDK | Authorization: Bearer vpt_… (an API token) | Every endpoint except most of /auth |
| The panel in a browser | The vp_session cookie, plus X-CSRF-Token on changes | Every endpoint |
| Plugins | Authorization: Bearer vpp_… (the plugin's own token) | What the owner approved |
| Billing systems | vpk_… billing API keys | /billing only |
| Server agents | Ed25519-signed requests | /agent only |
| Git hosts | A 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 (
trueorfalse).
The response envelope
Every response, success or error, has the same shape:
{
"success": true,
"data": { "status": "ok" },
"message": "OK",
"requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10"
}{
"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.
| Status | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | The request cannot be carried out as sent. |
| 400 | BAD_JSON | The body is not valid JSON. |
| 401 | UNAUTHENTICATED | No valid session or token. A revoked or expired token also answers this. |
| 403 | FORBIDDEN | Signed in, but without the permission (or CSRF token) this needs. |
| 403 | IP_NOT_ALLOWED | The panel only accepts approved addresses, and yours is not one. |
| 403 | TWO_FACTOR_SETUP_REQUIRED | Your account must turn on two-factor sign-in before it can use anything but /auth. |
| 404 | NOT_FOUND | No such record, or one you cannot see. Unknown routes also answer this. |
| 409 | CONFLICT and specific codes | The current state does not allow it. Most 409s have their own code, such as WEBSITE_BUSY or AGENT_OUTDATED. |
| 413 | PAYLOAD_TOO_LARGE | The body is over the size limit. |
| 422 | VALIDATION_ERROR | One or more fields are invalid. details lists them. |
| 429 | RATE_LIMITED | Too many requests. |
| 500 | INTERNAL_ERROR | Something failed on the panel. The message never contains internals. |
| 503 | DEGRADED | Only 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:
| Name | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number, from 1. |
pageSize | integer | 25 | Items per page, 1 to 100. |
sort | string | per endpoint | A column the endpoint allows, such as createdAt or name. |
order | string | per endpoint | asc 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 to | Limit |
|---|---|
Every endpoint under /api/v1 except /health, /agent, /hooks and /billing | 600 requests a minute |
| Sign-in, the second sign-in step, single sign-on, password changes and two-factor changes | 20 requests in 15 minutes |
POST /auth/setup | 10 requests in 15 minutes |
| Password reset requests and links | 20 requests in 15 minutes |
POST /hooks/deploy/:token | 30 requests a minute |
/billing | 120 requests a minute |
| Agent registration | 30 requests an hour |
| Agent install script and package downloads | 60 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.
{
"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 timeReads 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
/api/v1/healthWhether 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{ "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
Database schema
The tables in VaultPanel's MariaDB database by area, the migrations that add them, how secrets are stored at rest and how the audit log is protected.
Authentication
How callers authenticate to the VaultPanel API, and the /auth endpoints for setup, sign-in, two-factor codes, sessions and password resets.