# Servers

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

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

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](https://docs.vaultpanel.net/guides/servers/connecting-servers).

Operations on a server (restarting a service, rebooting, listing processes) are queued as jobs with [`POST /servers/:id/jobs`](https://docs.vaultpanel.net/api-reference/jobs#queue-an-operation).

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/servers` | [List servers](https://docs.vaultpanel.net/api-reference/servers#list-servers) |
| POST | `/api/v1/servers` | [Add a server](https://docs.vaultpanel.net/api-reference/servers#add-a-server) |
| GET | `/api/v1/servers/:id` | [Get a server](https://docs.vaultpanel.net/api-reference/servers#get-a-server) |
| PATCH | `/api/v1/servers/:id` | [Rename a server](https://docs.vaultpanel.net/api-reference/servers#rename-a-server) |
| DELETE | `/api/v1/servers/:id` | [Remove a server](https://docs.vaultpanel.net/api-reference/servers#remove-a-server) |
| POST | `/api/v1/servers/:id/enrollment-tokens` | [Create an enrollment token](https://docs.vaultpanel.net/api-reference/servers#create-an-enrollment-token) |
| GET | `/api/v1/servers/:id/metrics` | [Get metrics history](https://docs.vaultpanel.net/api-reference/servers#get-metrics-history) |
| POST | `/api/v1/servers/:id/jobs` | [Queue an operation](https://docs.vaultpanel.net/api-reference/jobs#queue-an-operation) (on the Jobs page) |
| PUT | `/api/v1/servers/:id/groups` | [Set a server's groups](https://docs.vaultpanel.net/api-reference/servers#set-a-servers-groups) |
| POST | `/api/v1/servers/:id/agent-update` | [Update the agent](https://docs.vaultpanel.net/api-reference/servers#update-the-agent) |
| POST | `/api/v1/servers/:id/terminal` | [Open a terminal](https://docs.vaultpanel.net/api-reference/servers#open-a-terminal) |
| GET | `/api/v1/terminal-sessions` | [List terminal sessions](https://docs.vaultpanel.net/api-reference/servers#list-terminal-sessions) |
| GET | `/api/v1/terminal-sessions/:id` | [Get a terminal session](https://docs.vaultpanel.net/api-reference/servers#get-a-terminal-session) |
| GET | `/api/v1/terminal-sessions/:id/recording` | [Download a recording](https://docs.vaultpanel.net/api-reference/servers#download-a-recording) |
| DELETE | `/api/v1/terminal-sessions/:id` | [Delete a recording](https://docs.vaultpanel.net/api-reference/servers#delete-a-recording) |
| GET | `/api/v1/terminal-sessions/settings` | [Get recording settings](https://docs.vaultpanel.net/api-reference/servers#get-recording-settings) |
| PUT | `/api/v1/terminal-sessions/settings` | [Change recording settings](https://docs.vaultpanel.net/api-reference/servers#change-recording-settings) |
| GET | `/api/v1/dashboard` | [Get the dashboard summary](https://docs.vaultpanel.net/api-reference/servers#get-the-dashboard-summary) |

## The server object

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

| Field | Description |
| --- | --- |
| `status` | `pending` (no agent yet), `online`, `offline` (the agent stopped reporting) or `disabled`. |
| `isLocal` | The server the panel itself runs on, connected automatically. |
| `services`, `filesystems` | The agent's latest snapshot, sent with every heartbeat. |
| `agentOperations` | The operations this agent reports it supports. Queuing anything else answers `409 AGENT_OUTDATED`. |
| `webStack` | What the agent found installed, such as NGINX, Certbot, Git, MariaDB and the PHP versions. The example shows some of its fields. `null` until reported. |
| `selfCheck` | The agent's last [self-check](https://docs.vaultpanel.net/guides/servers/self-check) report (agent 0.39.0 and later), or `null`. |
| `timezone` | The server's own time zone, which cron jobs run in. |
| `customerDns` | The name servers hosting customers on this server are shown, and whether their domains get DNS zones automatically. |

## List servers

`GET /api/v1/servers` — 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](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Matches name, host name or public IP. |
| `status` | string | No | `pending`, `online`, `offline` or `disabled`. |
| `groupId` | string | No | Only servers in this [group](https://docs.vaultpanel.net/api-reference/server-groups). |
| `sort` | string | No | `createdAt` (default), `name` or `lastSeenAt`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/servers?status=online" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.servers.list({ status: 'online' });
```

**Response** `200 OK`

```json
{
  "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](https://docs.vaultpanel.net/api-reference/servers#the-server-object); the example shows only the fields lists add.

## Add a server

`POST /api/v1/servers` — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1 to 100 letters, numbers, spaces and `. _ - ( )`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/servers \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"web-2"}'
```

**JavaScript**

```js
const { server, enrollment } = await panel.servers.create({ name: 'web-2' });
console.log(enrollment.installCommand);
```

**Response** `201 Created`

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

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | You lack `servers.manage`. |
| 422 | `VALIDATION_ERROR` | The name is missing or has characters that are not allowed. |

## Get a server

`GET /api/v1/servers/:id` — 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**

```bash
curl https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const server = await panel.servers.get(serverId);
```

**Response** `200 OK`. [The server object](https://docs.vaultpanel.net/api-reference/servers#the-server-object) plus:

```json
{
  "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](https://docs.vaultpanel.net/api-reference/servers#update-the-agent) can do it; otherwise run `command` on the server. `pendingEnrollment` holds the expiry of an unused token.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |

## Rename a server

`PATCH /api/v1/servers/:id` — Permission: servers.manage — Token scope: servers

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1 to 100 letters, numbers, spaces and `. _ - ( )`. |

**Example request**

**cURL**

```bash
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)"}'
```

**JavaScript**

```js
const server = await panel.servers.update(serverId, { name: 'web-1 (Frankfurt)' });
```

**Response** `200 OK` with the server, as from [Get a server](https://docs.vaultpanel.net/api-reference/servers#get-a-server).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |
| 422 | `VALIDATION_ERROR` | The name is invalid. |

## Remove a server

`DELETE /api/v1/servers/:id` — 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**

```bash
curl -X DELETE https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.servers.remove(serverId);
```

**Response** `200 OK`

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

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |

## Create an enrollment token

`POST /api/v1/servers/:id/enrollment-tokens` — 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**

```bash
curl -X POST https://panel.example.com/api/v1/servers/4d8e2f1a-6b3c-4a5d-8e9f-1a2b3c4d5e6f/enrollment-tokens \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { token, expiresAt, installCommand } = await panel.servers.enrollmentToken(serverId);
```

**Response** `201 Created`

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

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |

## Get metrics history

`GET /api/v1/servers/:id/metrics` — 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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `range` | string | No | `1h` (default), `6h`, `24h` (raw), or `7d`, `30d`, `90d` (hourly). |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/metrics?range=7d" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { resolution, points } = await panel.servers.metrics(serverId, { range: '7d' });
```

**Response** `200 OK`

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

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |
| 422 | `VALIDATION_ERROR` | `range` is not one of the values above. |

## Set a server's groups

`PUT /api/v1/servers/:id/groups` — Permission: servers.manage — Token scope: servers

Replaces the list of [groups](https://docs.vaultpanel.net/api-reference/server-groups) a server is in. An empty list takes it out of every group.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `groupIds` | string[] | Yes | Up to 50 group ids. |

**Example request**

**cURL**

```bash
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"]}'
```

**JavaScript**

```js
const groups = await panel.request('PUT', `/servers/${serverId}/groups`, { body: { groupIds: [groupId] } });
```

**Response** `200 OK`

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

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | One of the groups was not found. |
| 422 | `VALIDATION_ERROR` | The server was not found, or an id is not a UUID. |

## Update the agent

`POST /api/v1/servers/:id/agent-update` — 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](https://docs.vaultpanel.net/api-reference/servers#get-a-server) run on the server. To update many servers at once, use a [bulk action](https://docs.vaultpanel.net/api-reference/server-groups#start-a-bulk-action).

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/agent-update \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const job = await panel.servers.updateAgent(serverId);
await panel.jobs.wait(job.id);
```

**Response** `202 Accepted` with the [job](https://docs.vaultpanel.net/api-reference/jobs#the-job-object), message `Agent update queued`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such server. |
| 409 | `AGENT_CURRENT` | The agent is already on the newest version. |
| 409 | `AGENT_OUTDATED` | The agent is too old to update itself. Run the upgrade command on the server. |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `DUPLICATE_OPERATION` | An update is already queued or running (`details.jobId`). |

## Open a terminal

`POST /api/v1/servers/:id/terminal` — Auth: session — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cols` | integer | No | Terminal width, 2 to 1000. Default 80. |
| `rows` | integer | No | Terminal height, 2 to 500. Default 24. |

**Example request**

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

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

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | You are not an owner, or the request did not come from a browser session. |
| 404 | `NOT_FOUND` | No such server. |
| 409 | `SERVER_OFFLINE` | The server is not online. |
| 409 | `AGENT_TOO_OLD` | The agent is older than 0.11.0. |
| 409 | `TERMINAL_NOT_CONNECTED` | The agent has not connected its terminal channel yet. Try again in a few seconds. |
| 409 | `TERMINAL_DISABLED` | The terminal is turned off on this server. |
| 429 | `TOO_MANY_TERMINALS` | 5 terminals are open on this server, or 10 are open for you. |

## Terminal sessions

Past terminal sessions and their recordings, in [asciicast](https://docs.asciinema.org/manual/asciicast/v2/) format. Like the terminal itself these need `servers.terminal`, so in practice an owner's browser session. See [Terminal](https://docs.vaultpanel.net/guides/servers/terminal).

### The session object

```json
{
  "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 — Permission: servers.terminal

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page`, `pageSize` | integer | No | Paging, as for other lists. |
| `serverId` | string | No | Sessions on one server. |
| `userId` | string | No | Sessions of one person. |

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

## Get a terminal session

`GET /api/v1/terminal-sessions/:id` — Auth: session — 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 — 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**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No 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 — Permission: servers.terminal

Deletes a closed session's recording.

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

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such session. |
| 409 | `SESSION_OPEN` | The session is still open. |

## Get recording settings

`GET /api/v1/terminal-sessions/settings` — Auth: session — Permission: servers.terminal

**Response** `200 OK`

```json
{ "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 — Permission: servers.terminal

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | Record new sessions. |
| `recordInput` | boolean | Yes | Also record what is typed (passwords typed at prompts included). |
| `retentionDays` | integer | Yes | 1 to 3650. Older recordings are deleted. |
| `maxSizeMb` | integer | Yes | 1 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` — 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**

```bash
curl https://panel.example.com/api/v1/dashboard \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const summary = await panel.dashboard();
```

**Response** `200 OK`

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

| Section | Needs |
| --- | --- |
| `servers` | `servers.read` |
| `websites`, `applications`, `databases`, `backups`, `cron` | The matching `.read` permission |
| `jobs`, `recentJobs` | `jobs.read` (the 6 most recent jobs, routine ones left out) |
| `recentActivity` | `audit.read` (the 8 most recent audit log entries) |
| `alerts` | `alerts.read` |
| `users` | `users.read` |
