API Reference

Server groups and bulk actions

API reference for server groups and bulk actions, which run one operation on many servers at once, in parallel or one server at a time.

Last updated

Server groups collect servers you watch and act on together, such as "Production" or "Frankfurt". A server can be in several groups. Bulk actions run one operation on a set of servers, or on a group, and track each server's part. See Server groups.

To change the groups of one server, use PUT /servers/:id/groups.

Endpoints

MethodPathDescription
GET/api/v1/server-groupsList groups
POST/api/v1/server-groupsCreate a group
GET/api/v1/server-groups/:idGet a group
PATCH/api/v1/server-groups/:idUpdate a group
DELETE/api/v1/server-groups/:idDelete a group
GET/api/v1/bulk-actionsList bulk actions
POST/api/v1/bulk-actionsStart a bulk action
GET/api/v1/bulk-actions/:idGet a bulk action
POST/api/v1/bulk-actions/:id/cancelCancel a bulk action

The group summary

Group responses include a summary of their servers. Averages and highest values use only servers that are online and have reported metrics.

{
  "total": 3,
  "online": 3,
  "offline": 0,
  "pending": 0,
  "disabled": 0,
  "firingAlerts": 1,
  "agentsOutdated": 0,
  "cpu": { "average": 18.2, "max": 41.0 },
  "memory": { "average": 46.7, "max": 63.1 },
  "disk": { "average": 31.5, "max": 52.8 }
}

cpu, memory and disk are percentages, or null when no server has data.

List groups

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

Every group, by name, with its servers and summary.

Example request

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

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
        "name": "Production",
        "description": "Customer-facing servers",
        "color": "green",
        "createdAt": "2026-10-22T09:00:00.000Z",
        "updatedAt": "2026-10-22T09:00:00.000Z",
        "servers": [{ "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "status": "online" }],
        "summary": { "total": 1, "online": 1, "offline": 0, "pending": 0, "disabled": 0, "firingAlerts": 0, "agentsOutdated": 0, "cpu": { "average": 12.4, "max": 12.4 }, "memory": { "average": 38.6, "max": 38.6 }, "disk": { "average": 24.5, "max": 24.5 } }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

This list is not paginated.

Create a group

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

Request body

FieldTypeRequiredDescription
namestringYesUp to 60 letters, numbers, spaces and . _ - ( ) &, starting with a letter or number. Unique.
descriptionstringNoUp to 300 characters.
colorstringNoblue (default), green, amber, red, purple, teal or gray.
serverIdsstring[]NoUp to 500 servers to put in the group.

Example request

curl https://panel.example.com/api/v1/server-groups \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Production","color":"green","serverIds":["1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b"]}'
const group = await panel.servers.groups.create({
  name: 'Production',
  color: 'green',
  serverIds: [serverId],
});

Response 201 Created with the group, as from Get a group.

Errors

StatusCodeWhen
409GROUP_EXISTSA group with this name already exists.
422VALIDATION_ERRORA field is invalid, or one of the servers was not found.

Get a group

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

The group with its full server records: each server's fields, latest metrics, firing alert count and whether its agent is outdated.

Example request

curl https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const group = await panel.servers.groups.get(groupId);

Response 200 OK

{
  "success": true,
  "data": {
    "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
    "name": "Production",
    "description": "Customer-facing servers",
    "color": "green",
    "servers": [
      { "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "status": "online", "latestMetrics": { "cpuPercent": 12.4 }, "firingAlerts": 0, "agentOutdated": false }
    ],
    "summary": { "total": 1, "online": 1, "offline": 0, "pending": 0, "disabled": 0, "firingAlerts": 0, "agentsOutdated": 0, "cpu": { "average": 12.4, "max": 12.4 }, "memory": { "average": 38.6, "max": 38.6 }, "disk": { "average": 24.5, "max": 24.5 } }
  },
  "message": "OK",
  "requestId": "…"
}

Each server carries every field of the server object.

Errors

StatusCodeWhen
404NOT_FOUNDNo such group.

Update a group

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

Changes any of name, description, color and serverIds (same rules as Create a group). serverIds replaces the whole membership. Send at least one field.

Example request

curl -X PATCH https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"description":"Customer-facing servers in Frankfurt"}'
const group = await panel.servers.groups.update(groupId, { description: 'Customer-facing servers in Frankfurt' });

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

Errors

StatusCodeWhen
404NOT_FOUNDNo such group.
409GROUP_EXISTSAnother group has this name.
422VALIDATION_ERRORNo fields, an invalid field, or a server that was not found.

Delete a group

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

Deletes the group only. Its servers and past bulk actions stay.

Example request

curl -X DELETE https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.servers.groups.remove(groupId);

Response 200 OK with data: null, message Group deleted. Its servers were not changed.

Errors

StatusCodeWhen
404NOT_FOUNDNo such group.

Bulk actions

A bulk action runs one operation on up to 200 servers. Each server's part is an ordinary job linked back to the action.

OperationWhat it doesDefault modeChecked after the job
SERVICE_RESTARTRestart the same systemd service on every server (params.service)parallelNo
SERVICE_STARTStart a stopped service (params.service)parallelNo
SERVICE_STATUSRead a service's state (params.service)parallelNo
SECURITY_UPDATES_INSTALLInstall waiting security updates with unattended-upgradesrollingNo
AGENT_UPDATEInstall the agent version this panel serves (the panel fills in the version and checksum)parallelThe new version must be reported, within 3 minutes
SERVER_REBOOTRestart the serversrollingA newer boot time must be reported, within 10 minutes

Modes. parallel starts every server at once. rolling runs one server at a time: each must finish (and pass its check) before the next starts, and with stopOnFailure a failure stops the rest.

Skipped servers. Servers that are offline, have no agent, run an agent that cannot do the operation, or (for agent updates) are already current are skipped with the reason. If no server can run it, the action is refused with 409 NOTHING_TO_RUN.

The panel's own server (isLocal) always runs last. For SERVER_REBOOT it also waits until every other server is done, even in parallel mode, and its reboot is given 24 hours to be confirmed, since the panel is down until it is started again.

A target goes waiting, then running, then succeeded or failed; reboots and agent updates pass through verifying while the panel waits for their check. The action is running until every target is final, then succeeded, failed or cancelled.

List bulk actions

GET/api/v1/bulk-actions
Auth
Session cookie (+ CSRF token) or API token
Permission
jobs.read
Token scope
read

Bulk actions, newest first, with counts per target status. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
statusstringNorunning, succeeded, failed or cancelled.
groupIdstringNoActions started on one group.

Example request

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

Response 200 OK: { items: [action], pagination }, each action as below without targets.

Start a bulk action

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

Starts an operation on a list of servers or on every server of a group. You need servers.bulk and the operation's own permission (for example servers.reboot).

Request body

FieldTypeRequiredDescription
typestringYesOne of the operations above.
paramsobjectNoThe operation's parameters, such as { "service": "nginx" }.
serverIdsstring[]One of the twoUp to 200 servers.
groupIdstringOne of the twoEvery server in this group.
modestringNoparallel or rolling. Defaults to the operation's default.
stopOnFailurebooleanNoFor rolling mode: stop at the first failure. Default true.

Example request

curl https://panel.example.com/api/v1/bulk-actions \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"SECURITY_UPDATES_INSTALL","groupId":"c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e","mode":"rolling"}'
const action = await panel.bulkActions.create({
  type: 'SERVICE_RESTART',
  params: { service: 'php8.3-fpm' },
  groupId,
});

Response 202 Accepted

{
  "success": true,
  "data": {
    "id": "e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a",
    "type": "SECURITY_UPDATES_INSTALL",
    "label": "Install security updates",
    "params": {},
    "mode": "rolling",
    "stopOnFailure": true,
    "status": "running",
    "group": { "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e", "name": "Production" },
    "requestedBy": { "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "email": "ada@example.com" },
    "counts": { "total": 3, "waiting": 2, "running": 1, "verifying": 0, "succeeded": 0, "failed": 0, "skipped": 0, "cancelled": 0 },
    "cancelledAt": null,
    "createdAt": "2026-11-10T11:20:00.000Z",
    "finishedAt": null,
    "targets": [
      {
        "id": "f1e2d3c4-…",
        "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
        "serverName": "web-1",
        "position": 0,
        "status": "running",
        "message": null,
        "jobId": "a7b8c9d0-…",
        "jobStatus": "running",
        "isLocal": false,
        "verifyUntil": null,
        "startedAt": "2026-11-10T11:20:00.000Z",
        "finishedAt": null
      }
    ]
  },
  "message": "Bulk action started",
  "requestId": "…"
}

Errors

StatusCodeWhen
403FORBIDDENYou lack servers.bulk or the operation's permission.
404NOT_FOUNDThe group was not found.
409GROUP_EMPTYThe group has no servers.
409NOTHING_TO_RUNNo server can run it. details.servers lists each server with its reason.
422VALIDATION_ERRORNot exactly one of serverIds and groupId, an unknown type, invalid params, a server that was not found, or more than 200 servers.

Get a bulk action

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

The action with one target per server, in the order they run.

Example request

curl https://panel.example.com/api/v1/bulk-actions/e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const action = await panel.bulkActions.get(actionId);

Response 200 OK with the action, as from Start a bulk action.

Errors

StatusCodeWhen
404NOT_FOUNDNo such bulk action.

Cancel a bulk action

POST/api/v1/bulk-actions/:id/cancel
Auth
Session cookie (+ CSRF token) or API token
Permission
servers.bulk
Token scope
servers

Cancels the servers that have not started yet, including jobs still waiting for their agent. Anything already running on a server finishes.

Example request

curl -X POST https://panel.example.com/api/v1/bulk-actions/e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a/cancel \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const action = await panel.bulkActions.cancel(actionId);

Response 200 OK with the action, message Servers that had not started were cancelled.

Errors

StatusCodeWhen
404NOT_FOUNDNo such bulk action.
409NOT_RUNNINGThe action has already finished.