API Reference

Servers

API reference for servers, enrollment tokens and agent install commands, metrics history, agent updates, terminal sessions and the dashboard summary.

Last updated

A server is a machine the panel manages through its agent. Adding one creates a record in pending state and a one-time enrollment token; the server becomes online once its agent registers and reports in. See Connecting servers.

Operations on a server (restarting a service, rebooting, listing processes) are queued as jobs with POST /servers/:id/jobs.

Endpoints

MethodPathDescription
GET/api/v1/serversList servers
POST/api/v1/serversAdd a server
GET/api/v1/servers/:idGet a server
PATCH/api/v1/servers/:idRename a server
DELETE/api/v1/servers/:idRemove a server
POST/api/v1/servers/:id/enrollment-tokensCreate an enrollment token
GET/api/v1/servers/:id/metricsGet metrics history
POST/api/v1/servers/:id/jobsQueue an operation (on the Jobs page)
PUT/api/v1/servers/:id/groupsSet a server's groups
POST/api/v1/servers/:id/agent-updateUpdate the agent
POST/api/v1/servers/:id/terminalOpen a terminal
GET/api/v1/terminal-sessionsList terminal sessions
GET/api/v1/terminal-sessions/:idGet a terminal session
GET/api/v1/terminal-sessions/:id/recordingDownload a recording
DELETE/api/v1/terminal-sessions/:idDelete a recording
GET/api/v1/terminal-sessions/settingsGet recording settings
PUT/api/v1/terminal-sessions/settingsChange recording settings
GET/api/v1/dashboardGet the dashboard summary

The server object

{
  "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "name": "web-1",
  "status": "online",
  "isLocal": false,
  "hostname": "web-1",
  "publicIp": "203.0.113.10",
  "os": { "name": "Ubuntu", "version": "24.04", "kernel": "6.8.0-48-generic", "architecture": "x64" },
  "cpuCores": 4,
  "memoryTotalBytes": 8336568320,
  "diskTotalBytes": 168488570880,
  "uptimeSeconds": 1209600,
  "timezone": "Etc/UTC",
  "agentVersion": "0.41.0",
  "lastSeenAt": "2026-11-10T11:05:30.000Z",
  "services": [
    { "name": "nginx", "loadState": "loaded", "active": "active", "sub": "running", "enabled": "enabled", "description": "A high performance web server and a reverse proxy server" }
  ],
  "filesystems": [{ "mount": "/", "device": "/dev/sda1", "fsType": "ext4", "totalBytes": 168488570880, "usedBytes": 41203298304 }],
  "agentOperations": ["SERVICE_STATUS", "SERVICE_RESTART", "PROCESS_LIST", "SERVER_REBOOT"],
  "webStack": { "nginx": true, "certbot": true, "git": true, "mariadb": true, "phpVersions": ["8.3"] },
  "selfCheck": null,
  "ipAddresses": ["203.0.113.10"],
  "customerDns": { "nameservers": [], "autoZones": false },
  "createdAt": "2026-10-20T08:10:00.000Z",
  "updatedAt": "2026-11-10T11:05:30.000Z"
}
FieldDescription
statuspending (no agent yet), online, offline (the agent stopped reporting) or disabled.
isLocalThe server the panel itself runs on, connected automatically.
services, filesystemsThe agent's latest snapshot, sent with every heartbeat.
agentOperationsThe operations this agent reports it supports. Queuing anything else answers 409 AGENT_OUTDATED.
webStackWhat the agent found installed, such as NGINX, Certbot, Git, MariaDB and the PHP versions. The example shows some of its fields. null until reported.
selfCheckThe agent's last self-check report (agent 0.39.0 and later), or null.
timezoneThe server's own time zone, which cron jobs run in.
customerDnsThe name servers hosting customers on this server are shown, and whether their domains get DNS zones automatically.

List servers

GET/api/v1/servers
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.read
Token scope
read

Servers, newest first, each with its latest metrics, its groups and whether a newer agent is available. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches name, host name or public IP.
statusstringNopending, online, offline or disabled.
groupIdstringNoOnly servers in this group.
sortstringNocreatedAt (default), name or lastSeenAt.

Example request

curl "https://panel.example.com/api/v1/servers?status=online" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.servers.list({ status: 'online' });

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
        "name": "web-1",
        "status": "online",
        "latestMetrics": {
          "collectedAt": "2026-11-10T11:05:30.000Z",
          "cpuPercent": 12.4,
          "load": [0.42, 0.38, 0.35],
          "memoryUsedBytes": 3221225472,
          "memoryTotalBytes": 8336568320,
          "swapUsedBytes": 0,
          "swapTotalBytes": 2147483648,
          "diskUsedBytes": 41203298304,
          "diskTotalBytes": 168488570880,
          "netRxBytesPerSec": 18234,
          "netTxBytesPerSec": 9120,
          "processCount": 187,
          "uptimeSeconds": 1209600
        },
        "groups": [{ "id": "c2d4…", "name": "Production", "color": "green" }],
        "agentUpdateAvailable": false
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}

Each item carries every field of the server object; the example shows only the fields lists add.

Add a server

POST/api/v1/servers
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Creates a server record and its first enrollment token. Run the returned install command on the server, as root, to install and register the agent. The token is valid for 60 minutes by default (VAULTPANEL_ENROLLMENT_TTL_MINUTES) and only once.

When the panel serves its own self-signed certificate, the command carries the certificate's public key pin, so the agent trusts exactly that certificate.

Request body

FieldTypeRequiredDescription
namestringYes1 to 100 letters, numbers, spaces and . _ - ( ).

Example request

curl https://panel.example.com/api/v1/servers \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"web-2"}'
const { server, enrollment } = await panel.servers.create({ name: 'web-2' });
console.log(enrollment.installCommand);

Response 201 Created

{
  "success": true,
  "data": {
    "server": { "id": "4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f", "name": "web-2", "status": "pending", "agentVersion": null, "createdAt": "…" },
    "enrollment": {
      "token": "vpe_…",
      "expiresAt": "2026-11-10T12:10:00.000Z",
      "installCommand": "curl -fsSL --pinnedpubkey 'sha256//…' -k https://panel.example.com/api/v1/agent/install.sh | sudo bash -s -- --panel https://panel.example.com --token vpe_… --panel-pin 'sha256//…'"
    }
  },
  "message": "Server added. Run the install command on it to connect the agent.",
  "requestId": "…"
}

Errors

StatusCodeWhen
403FORBIDDENYou lack servers.manage.
422VALIDATION_ERRORThe name is missing or has characters that are not allowed.

Get a server

GET/api/v1/servers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.read
Token scope
read

The server with its latest metrics, groups, registered agent, any unused enrollment token and agent update information.

Example request

curl https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const server = await panel.servers.get(serverId);

Response 200 OK. The server object plus:

{
  "latestMetrics": { "collectedAt": "…", "cpuPercent": 12.4 },
  "groups": [{ "id": "c2d4…", "name": "Production", "color": "green" }],
  "agent": {
    "id": "b7c8…",
    "keyFingerprint": "SHA256:…",
    "version": "0.40.0",
    "registeredAt": "2026-10-20T08:12:44.000Z",
    "registeredIp": "203.0.113.10",
    "lastSeenAt": "2026-11-10T11:05:30.000Z"
  },
  "pendingEnrollment": null,
  "agentUpdate": {
    "currentVersion": "0.40.0",
    "latestVersion": "0.41.0",
    "fromPanel": true,
    "command": "curl -fsSL … | sudo bash -s -- --upgrade --panel https://panel.example.com …"
  }
}

agentUpdate is null when the agent is current. fromPanel says whether Update the agent can do it; otherwise run command on the server. pendingEnrollment holds the expiry of an unused token.

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.

Rename a server

PATCH/api/v1/servers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Request body

FieldTypeRequiredDescription
namestringYes1 to 100 letters, numbers, spaces and . _ - ( ).

Example request

curl -X PATCH https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"web-1 (Frankfurt)"}'
const server = await panel.servers.update(serverId, { name: 'web-1 (Frankfurt)' });

Response 200 OK with the server, as from Get a server.

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.
422VALIDATION_ERRORThe name is invalid.

Remove a server

DELETE/api/v1/servers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Removes the server from the panel, revokes its agent, invalidates its enrollment tokens and cancels its queued jobs. Nothing on the server itself is touched; the agent stops working once revoked.

Example request

curl -X DELETE https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.servers.remove(serverId);

Response 200 OK

{ "success": true, "data": null, "message": "Server removed and its agent revoked", "requestId": "…" }

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.

Create an enrollment token

POST/api/v1/servers/:id/enrollment-tokens
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Issues a new enrollment token and install command for a server, for example when the first one expired. Only the newest token works: older unused ones stop working.

Example request

curl -X POST https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f/enrollment-tokens \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { token, expiresAt, installCommand } = await panel.servers.enrollmentToken(serverId);

Response 201 Created

{
  "success": true,
  "data": { "token": "vpe_…", "expiresAt": "2026-11-10T12:20:00.000Z", "installCommand": "curl -fsSL … | sudo bash -s -- --panel https://panel.example.com --token vpe_…" },
  "message": "New enrollment token created; older ones no longer work",
  "requestId": "…"
}

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.

Get metrics history

GET/api/v1/servers/:id/metrics
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.read
Token scope
read

CPU, memory, swap, disk, network and process history. Short ranges return the agent's raw 15-second samples, averaged down to at most 240 points. Long ranges return hourly rollups, which add the hour's highest CPU and the number of samples.

Query parameters

NameTypeRequiredDescription
rangestringNo1h (default), 6h, 24h (raw), or 7d, 30d, 90d (hourly).

Example request

curl "https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/metrics?range=7d" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { resolution, points } = await panel.servers.metrics(serverId, { range: '7d' });

Response 200 OK

{
  "success": true,
  "data": {
    "range": "7d",
    "resolution": "hour",
    "points": [
      {
        "collectedAt": "2026-11-03T12:00:00.000Z",
        "cpuPercent": 9.8,
        "cpuPercentMax": 41.2,
        "samples": 240,
        "load": [0.31, 0.29, 0.27],
        "memoryUsedBytes": 3105423360,
        "memoryTotalBytes": 8336568320,
        "swapUsedBytes": 0,
        "swapTotalBytes": 2147483648,
        "diskUsedBytes": 40961949696,
        "diskTotalBytes": 168488570880,
        "netRxBytesPerSec": 15022,
        "netTxBytesPerSec": 8411,
        "processCount": 184,
        "uptimeSeconds": null
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

resolution is raw for 1h, 6h and 24h, and hour otherwise. Raw points have no cpuPercentMax or samples.

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.
422VALIDATION_ERRORrange is not one of the values above.

Set a server's groups

PUT/api/v1/servers/:id/groups
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Replaces the list of groups a server is in. An empty list takes it out of every group.

Request body

FieldTypeRequiredDescription
groupIdsstring[]YesUp to 50 group ids.

Example request

curl -X PUT https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/groups \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"groupIds":["c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e"]}'
const groups = await panel.request('PUT', `/servers/${serverId}/groups`, { body: { groupIds: [groupId] } });

Response 200 OK

{ "success": true, "data": [{ "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e", "name": "Production", "color": "green" }], "message": "Groups saved", "requestId": "…" }

Errors

StatusCodeWhen
404NOT_FOUNDOne of the groups was not found.
422VALIDATION_ERRORThe server was not found, or an id is not a UUID.

Update the agent

POST/api/v1/servers/:id/agent-update
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.manage
Token scope
servers

Queues an AGENT_UPDATE job that installs the agent version this panel serves, checked against its SHA-256. Agents 0.7.0 and later can update themselves this way; older agents need the agentUpdate.command from Get a server run on the server. To update many servers at once, use a bulk action.

Example request

curl -X POST https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/agent-update \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const job = await panel.servers.updateAgent(serverId);
await panel.jobs.wait(job.id);

Response 202 Accepted with the job, message Agent update queued.

Errors

StatusCodeWhen
404NOT_FOUNDNo such server.
409AGENT_CURRENTThe agent is already on the newest version.
409AGENT_OUTDATEDThe agent is too old to update itself. Run the upgrade command on the server.
409SERVER_NOT_READYThe server has no connected agent yet.
409DUPLICATE_OPERATIONAn update is already queued or running (details.jobId).

Open a terminal

POST/api/v1/servers/:id/terminal
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Issues a one-time ticket for a root terminal on the server. The browser then opens a WebSocket at the returned path within 30 seconds. Only owners have servers.terminal, and the terminal opens only from a browser session: API tokens, plugins and the AI assistant are always refused. Every session is audited and, by default, recorded. Needs agent 0.11.0 or later.

Request body

FieldTypeRequiredDescription
colsintegerNoTerminal width, 2 to 1000. Default 80.
rowsintegerNoTerminal height, 2 to 500. Default 24.

Example request

const res = await fetch(`/api/v1/servers/${serverId}/terminal`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
  body: JSON.stringify({ cols: 120, rows: 32 }),
});
const { data } = await res.json();
const socket = new WebSocket(`wss://${location.host}${data.path}`);

Response 201 Created

{ "success": true, "data": { "ticket": "…", "path": "/api/v1/terminal/connect?ticket=…", "expiresInSeconds": 30 }, "message": "OK", "requestId": "…" }

Errors

StatusCodeWhen
403FORBIDDENYou are not an owner, or the request did not come from a browser session.
404NOT_FOUNDNo such server.
409SERVER_OFFLINEThe server is not online.
409AGENT_TOO_OLDThe agent is older than 0.11.0.
409TERMINAL_NOT_CONNECTEDThe agent has not connected its terminal channel yet. Try again in a few seconds.
409TERMINAL_DISABLEDThe terminal is turned off on this server.
429TOO_MANY_TERMINALS5 terminals are open on this server, or 10 are open for you.

Terminal sessions

Past terminal sessions and their recordings, in asciicast format. Like the terminal itself these need servers.terminal, so in practice an owner's browser session. See Terminal.

The session object

{
  "id": "e3f1a2b4-…",
  "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "serverName": "web-1",
  "userId": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07",
  "userLabel": "ada@example.com",
  "ip": "198.51.100.24",
  "cols": 120,
  "rows": 32,
  "startedAt": "2026-11-10T10:00:02.000Z",
  "endedAt": "2026-11-10T10:12:47.000Z",
  "seconds": 765,
  "exitCode": 0,
  "endReason": "exit",
  "outputBytes": 48211,
  "recording": "output",
  "recordingBytes": 51002,
  "recordingTruncated": false
}

recording is off, output or output_input (keystrokes too).

List terminal sessions

GET/api/v1/terminal-sessions
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Query parameters

NameTypeRequiredDescription
page, pageSizeintegerNoPaging, as for other lists.
serverIdstringNoSessions on one server.
userIdstringNoSessions of one person.

Response 200 OK: { items: [session], pagination }.

Get a terminal session

GET/api/v1/terminal-sessions/:id
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Response 200 OK with the session object. 404 NOT_FOUND when there is no such session.

Download a recording

GET/api/v1/terminal-sessions/:id/recording
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Streams the recording as application/x-asciicast. Add ?download=1 to receive it as an attachment named after the server and start time.

Errors

StatusCodeWhen
404NOT_FOUNDNo such session, it was not recorded, or the file was removed after the retention period.

Delete a recording

DELETE/api/v1/terminal-sessions/:id
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Deletes a closed session's recording.

Response 200 OK with data: null, message Recording deleted.

Errors

StatusCodeWhen
404NOT_FOUNDNo such session.
409SESSION_OPENThe session is still open.

Get recording settings

GET/api/v1/terminal-sessions/settings
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Response 200 OK

{ "success": true, "data": { "enabled": true, "recordInput": false, "retentionDays": 90, "maxSizeMb": 50 }, "message": "OK", "requestId": "…" }

The values shown are the defaults.

Change recording settings

PUT/api/v1/terminal-sessions/settings
Auth
Session cookie only (API tokens are refused)
Permission
servers.terminal

Request body

FieldTypeRequiredDescription
enabledbooleanYesRecord new sessions.
recordInputbooleanYesAlso record what is typed (passwords typed at prompts included).
retentionDaysintegerYes1 to 3650. Older recordings are deleted.
maxSizeMbintegerYes1 to 1024. A longer session's recording is truncated.

Response 200 OK with the saved settings, message Terminal recording settings saved.

Get the dashboard summary

GET/api/v1/dashboard
Auth
Session cookie (+ CSRF token) or API token
Permission
dashboard.view
Token scope
read

Counts for the panel's dashboard. Each section is filled only when you have the permission to see it, and is null otherwise.

Example request

curl https://panel.example.com/api/v1/dashboard \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const summary = await panel.dashboard();

Response 200 OK

{
  "success": true,
  "data": {
    "servers": { "total": 3, "byStatus": { "pending": 0, "online": 3, "offline": 0, "disabled": 0 } },
    "websites": { "total": 6, "byStatus": { "active": 6 }, "sslExpiring": 0 },
    "applications": { "total": 2, "busy": 0, "byProcess": { "running": 2 }, "deployments24h": { "succeeded": 3 } },
    "databases": { "total": 4, "byStatus": { "active": 4 }, "users": 4 },
    "backups": { "byStatus": { "succeeded": 28 }, "failedLastDay": 0, "schedules": 3, "totalBytes": 1873420288 },
    "cron": { "jobs": 5, "failedLastDay": 0 },
    "jobs": { "last24h": { "succeeded": 41, "failed": 1 } },
    "recentJobs": [],
    "recentActivity": [],
    "users": { "active": 5 },
    "alerts": { "firing": 0, "unacknowledged": 0, "bySeverity": {} }
  },
  "message": "OK",
  "requestId": "…"
}
SectionNeeds
serversservers.read
websites, applications, databases, backups, cronThe matching .read permission
jobs, recentJobsjobs.read (the 6 most recent jobs, routine ones left out)
recentActivityaudit.read (the 8 most recent audit log entries)
alertsalerts.read
usersusers.read