# API overview

URL: https://docs.vaultpanel.net/api-reference

> 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](https://docs.vaultpanel.net/cli), the [JavaScript SDK](https://docs.vaultpanel.net/developers/sdk) and [plugins](https://docs.vaultpanel.net/developers/plugins). This page covers the conventions every endpoint shares. The pages in this section document each endpoint.

## Base URL

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

> **Note:**
A new install serves the panel with a self-signed certificate (in `/etc/vaultpanel/tls/` on the panel's server). Give the panel a domain with a trusted certificate before you script against it, or point your client at that certificate, for example with `curl --cacert`. See [HTTPS and the panel domain](https://docs.vaultpanel.net/getting-started/panel-https-and-domain).

## 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](https://docs.vaultpanel.net/api-reference/api-tokens).

### Call the API

**cURL**

```bash
export VAULTPANEL_TOKEN=vpt_…
curl https://panel.example.com/api/v1/auth/me \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

```json
{
  "success": true,
  "data": { "status": "ok" },
  "message": "OK",
  "requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10"
}
```

```json
{
  "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`).

```json
{
  "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:

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

The SDK walks every page for you:

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

```json
{
  "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:

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

## Health

`GET /api/v1/health` — Auth: public

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

```bash
curl https://panel.example.com/api/v1/health
```

```json
{ "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](https://docs.vaultpanel.net/guides/hosting-and-billing).

## Endpoint reference

- [Authentication](https://docs.vaultpanel.net/api-reference/authentication)
- [API tokens](https://docs.vaultpanel.net/api-reference/api-tokens)
- [Users and roles](https://docs.vaultpanel.net/api-reference/users-and-roles)
- [Settings](https://docs.vaultpanel.net/api-reference/settings)
- [Servers](https://docs.vaultpanel.net/api-reference/servers)
- [Jobs](https://docs.vaultpanel.net/api-reference/jobs)
- [Server groups](https://docs.vaultpanel.net/api-reference/server-groups)
- [Monitoring and alerts](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts)
- [Security](https://docs.vaultpanel.net/api-reference/security)
- [Websites](https://docs.vaultpanel.net/api-reference/websites)
- [Applications](https://docs.vaultpanel.net/api-reference/applications)
- [Databases](https://docs.vaultpanel.net/api-reference/databases)
- [Containers](https://docs.vaultpanel.net/api-reference/containers)
- [DNS](https://docs.vaultpanel.net/api-reference/dns)
- [Mail](https://docs.vaultpanel.net/api-reference/mail)
- [Backups](https://docs.vaultpanel.net/api-reference/backups)
- [Cron jobs](https://docs.vaultpanel.net/api-reference/cron-jobs)
- [Webhooks](https://docs.vaultpanel.net/api-reference/webhooks)
- [Assistant](https://docs.vaultpanel.net/api-reference/assistant)
- [Hosting](https://docs.vaultpanel.net/api-reference/hosting)
- [Billing](https://docs.vaultpanel.net/api-reference/billing)
- [Plugins](https://docs.vaultpanel.net/api-reference/plugins)
- [Agent](https://docs.vaultpanel.net/api-reference/agent)
