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.
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
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/server-groups | List groups |
| POST | /api/v1/server-groups | Create a group |
| GET | /api/v1/server-groups/:id | Get a group |
| PATCH | /api/v1/server-groups/:id | Update a group |
| DELETE | /api/v1/server-groups/:id | Delete a group |
| GET | /api/v1/bulk-actions | List bulk actions |
| POST | /api/v1/bulk-actions | Start a bulk action |
| GET | /api/v1/bulk-actions/:id | Get a bulk action |
| POST | /api/v1/bulk-actions/:id/cancel | Cancel 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
/api/v1/server-groupsEvery 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
/api/v1/server-groupsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 60 letters, numbers, spaces and . _ - ( ) &, starting with a letter or number. Unique. |
description | string | No | Up to 300 characters. |
color | string | No | blue (default), green, amber, red, purple, teal or gray. |
serverIds | string[] | No | Up 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
| Status | Code | When |
|---|---|---|
| 409 | GROUP_EXISTS | A group with this name already exists. |
| 422 | VALIDATION_ERROR | A field is invalid, or one of the servers was not found. |
Get a group
/api/v1/server-groups/:idThe 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such group. |
Update a group
/api/v1/server-groups/:idChanges 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such group. |
| 409 | GROUP_EXISTS | Another group has this name. |
| 422 | VALIDATION_ERROR | No fields, an invalid field, or a server that was not found. |
Delete a group
/api/v1/server-groups/:idDeletes 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No 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.
| Operation | What it does | Default mode | Checked after the job |
|---|---|---|---|
SERVICE_RESTART | Restart the same systemd service on every server (params.service) | parallel | No |
SERVICE_START | Start a stopped service (params.service) | parallel | No |
SERVICE_STATUS | Read a service's state (params.service) | parallel | No |
SECURITY_UPDATES_INSTALL | Install waiting security updates with unattended-upgrades | rolling | No |
AGENT_UPDATE | Install the agent version this panel serves (the panel fills in the version and checksum) | parallel | The new version must be reported, within 3 minutes |
SERVER_REBOOT | Restart the servers | rolling | A 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
/api/v1/bulk-actionsBulk actions, newest first, with counts per target status. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | running, succeeded, failed or cancelled. |
groupId | string | No | Actions 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
/api/v1/bulk-actionsStarts 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
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of the operations above. |
params | object | No | The operation's parameters, such as { "service": "nginx" }. |
serverIds | string[] | One of the two | Up to 200 servers. |
groupId | string | One of the two | Every server in this group. |
mode | string | No | parallel or rolling. Defaults to the operation's default. |
stopOnFailure | boolean | No | For 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | You lack servers.bulk or the operation's permission. |
| 404 | NOT_FOUND | The group was not found. |
| 409 | GROUP_EMPTY | The group has no servers. |
| 409 | NOTHING_TO_RUN | No server can run it. details.servers lists each server with its reason. |
| 422 | VALIDATION_ERROR | Not 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
/api/v1/bulk-actions/:idThe 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such bulk action. |
Cancel a bulk action
/api/v1/bulk-actions/:id/cancelCancels 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such bulk action. |
| 409 | NOT_RUNNING | The action has already finished. |