Jobs
API reference for jobs, the asynchronous record of every change an agent makes, and the catalog of operations you can queue on a server.
A job is one operation an agent carries out on a server: creating a website, deploying an app, restarting a service. The panel never runs commands itself and there is no endpoint that runs arbitrary commands. Each job names an operation from a fixed catalog, the agent re-checks its parameters against its own allow-list, and runs fixed commands without a shell. See How it works.
Most jobs are started by the endpoint for the thing they change (POST /websites queues CREATE_SITE). A small set of server operations is queued directly with Queue an operation.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/jobs | List jobs |
| GET | /api/v1/jobs/:id | Get a job and its logs |
| POST | /api/v1/jobs/:id/cancel | Cancel a job |
| GET | /api/v1/jobs/operations | List operations |
| POST | /api/v1/servers/:id/jobs | Queue an operation |
Job lifecycle
queued ──> dispatched ──> running ──> succeeded
│ ├──────> failed
│ └──────> timed_out
└──> cancelled (only while queued)| Status | Meaning |
|---|---|
queued | Waiting for the agent to pick it up. A job no agent picks up within 5 minutes fails. |
dispatched | Handed to the agent, not started yet. |
running | The agent is carrying it out and streaming its log. |
succeeded, failed, timed_out, cancelled | Final. |
Retryable operations (status checks and reads) get up to 3 attempts; operations that change the server get one. Each operation has its own time limit.
When a job finishes, the record it acts on is updated before the agent's next request is answered, so a follow-up job always sees the result of the one before.
Duplicates
The panel refuses a job identical to one that is still queued, dispatched or running (same server, operation and parameters) with 409 DUPLICATE_OPERATION, and returns the existing job's id in details.jobId.
Routine jobs
Reads the interface waits on, such as file listings, log lines and status checks, are routine jobs. They are left out of GET /jobs unless you pass includeRoutine=true, and file contents are removed from stored jobs.
Redacted parameters
Passwords, environment values and written file contents in a job's parameters are replaced with { "redacted": true, "length": 42 } (or count for lists) whenever the job is shown or stored for the long term.
The job object
{
"id": "a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d",
"type": "SERVICE_RESTART",
"serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
"serverName": "web-1",
"status": "succeeded",
"params": { "service": "nginx" },
"resource": null,
"requestedBy": { "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "email": "ada@example.com" },
"attempts": 1,
"maxAttempts": 1,
"timeoutSeconds": 120,
"requestId": "6f1c2a4e-1b7d-4c55-9a0e-3d2f8b7c9e10",
"output": {
"service": { "name": "nginx", "loadState": "loaded", "active": "active", "sub": "running", "enabled": "enabled", "description": "A high performance web server and a reverse proxy server" }
},
"error": null,
"expiresAt": "2026-11-10T11:15:00.000Z",
"dispatchedAt": "2026-11-10T11:10:01.000Z",
"startedAt": "2026-11-10T11:10:01.000Z",
"finishedAt": "2026-11-10T11:10:03.000Z",
"durationMs": 2000,
"createdAt": "2026-11-10T11:10:00.000Z",
"updatedAt": "2026-11-10T11:10:03.000Z"
}| Field | Description |
|---|---|
resource | The record the job acts on, such as { "type": "website", "id": "…" }, or null. |
requestedBy | The person who queued it, or { "type": "system" } for the panel's own work. A hosting customer sees their provider's staff as { "type": "staff" }. |
output | What the operation returned. Its shape depends on the operation. |
error | { code, message } when the job failed. |
expiresAt | When a queued job fails if no agent has picked it up. |
List jobs
/api/v1/jobsJobs, newest first. Hosting customers see only jobs on their own records. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
serverId | string | No | Jobs on one server. |
status | string | No | One of the statuses above. |
type | string | No | One operation, such as DEPLOY_GIT. Routine jobs of that type are included. |
includeRoutine | boolean | No | Include routine jobs. Default false. |
sort | string | No | createdAt (default) or finishedAt. |
Example request
curl "https://panel.example.com/api/v1/jobs?status=failed&pageSize=10" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.jobs.list({ status: 'failed', pageSize: 10 });Response 200 OK: { items: [job], pagination }.
Get a job and its logs
/api/v1/jobs/:idThe job with its log lines. Poll it to follow a job: pass the highest log id you have seen as afterLogId to receive only newer lines. Each call returns up to 1000 lines.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
afterLogId | integer | No | Only log lines with a higher id. Default 0. |
Example request
curl "https://panel.example.com/api/v1/jobs/a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d?afterLogId=0" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"// Poll until the job is final, printing log lines as they arrive.
const { job, logs } = await panel.jobs.wait(jobId, {
timeoutMs: 600_000,
onProgress: (job, lines) => lines.forEach((line) => console.log(line.message)),
});Response 200 OK
{
"success": true,
"data": {
"id": "a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d",
"type": "SERVICE_RESTART",
"status": "succeeded",
"logs": [
{ "id": 90211, "stream": "system", "message": "Queued by ada@example.com", "loggedAt": "2026-11-10T11:10:00.000Z" },
{ "id": 90212, "stream": "system", "message": "Agent started the operation", "loggedAt": "2026-11-10T11:10:01.000Z" },
{ "id": 90213, "stream": "stdout", "message": "$ systemctl restart nginx.service", "loggedAt": "2026-11-10T11:10:01.000Z" }
]
},
"message": "OK",
"requestId": "…"
}The job's other fields are those of the job object. stream is system (the panel's own notes), stdout or stderr.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such job, or not one of yours (hosting customers). |
Cancel a job
/api/v1/jobs/:id/cancelCancels a job that is still queued. Once the agent has a job it may already be changing the server, so dispatched and running jobs cannot be cancelled.
Example request
curl -X POST https://panel.example.com/api/v1/jobs/a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d/cancel \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const job = await panel.jobs.cancel(jobId);Response 200 OK with the job, status: "cancelled".
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such job. |
| 409 | JOB_NOT_CANCELLABLE | The job is no longer queued. |
List operations
/api/v1/jobs/operationsThe whole operation catalog: every operation with its label, whether it is available in this release, the permission it needs and whether it is marked dangerous. Any signed-in caller may read it.
Example request
curl https://panel.example.com/api/v1/jobs/operations \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.jobs.operations();Response 200 OK
{
"success": true,
"data": {
"items": [
{ "type": "SERVICE_STATUS", "label": "Check service status", "available": true, "phase": null, "permission": "servers.services", "dangerous": false },
{ "type": "SERVER_REBOOT", "label": "Reboot server", "available": true, "phase": null, "permission": "servers.reboot", "dangerous": true }
]
},
"message": "OK",
"requestId": "…"
}Queue an operation
/api/v1/servers/:id/jobsQueues one of the direct operations on a server and answers 202 Accepted with the job. The permission checked is the operation's own; parameters are validated against the catalog, and their errors are reported as params.<name>. Hosting customers cannot queue operations on servers.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | The operation, such as SERVICE_RESTART. |
params | object | No | The operation's parameters. Default {}. |
Example request
curl https://panel.example.com/api/v1/servers/1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b/jobs \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
-d '{"type":"SERVICE_RESTART","params":{"service":"nginx"}}'const job = await panel.servers.runOperation(serverId, {
type: 'SERVICE_RESTART',
params: { service: 'nginx' },
});
const { job: done } = await panel.jobs.wait(job.id);Response 202 Accepted with the job object (status: "queued"), message Job queued.
Errors
| Status | Code | When |
|---|---|---|
| 400 | OPERATION_NOT_DIRECT | The operation is started by its own endpoint (websites, files, apps…), not directly. |
| 403 | FORBIDDEN | You lack the operation's permission, or you are a hosting customer. |
| 404 | NOT_FOUND | No such server. |
| 409 | OPERATION_UNAVAILABLE | The operation is in the catalog but not available in this release. |
| 409 | SERVER_NOT_READY | The server has no connected agent yet. |
| 409 | AGENT_OUTDATED | The server's agent does not support this operation. Update the agent. |
| 409 | DUPLICATE_OPERATION | The same operation is already queued or running (details.jobId). |
| 422 | VALIDATION_ERROR | Unknown type, or invalid params (params.service…). |
Direct operations
These operations can be queued with Queue an operation. The token scope column names the scope that grants the permission.
| Operation | What it does | Permission | Token scope | Parameters |
|---|---|---|---|---|
SERVICE_STATUS | Check a systemd service's state | servers.services | servers | service (required) |
SERVICE_START | Start a service | servers.services | servers | service (required) |
SERVICE_STOP | Stop a service (dangerous) | servers.services | servers | service (required) |
SERVICE_RESTART | Restart a service (dangerous) | servers.services | servers | service (required) |
SERVICE_LOGS | Read a service's journal | servers.services | servers | service (required), lines (10 to 1000, default 200) |
PROCESS_LIST | List running processes | servers.processes | servers | limit (1 to 500, default 50), sortBy (cpu or memory, default cpu) |
PROCESS_SIGNAL | Stop a process (dangerous) | servers.signal | servers | pid (required, 2 to 4194304), command (required, the process name you saw), signal (TERM or KILL, default TERM) |
LISTENING_PORTS | List listening ports (routine) | servers.processes | servers | None |
SELF_CHECK | Run the server self-check now (routine) | servers.read | read | None |
SERVER_REBOOT | Reboot the server (dangerous) | servers.reboot | servers | None |
WEB_STACK_INSTALL | Install server software | websites.manage | manage | components (required, 1 to 12 of nginx, php, certbot, apache, git, pm2, python, go, ruby, composer, mariadb, cron) |
PHP_VERSION_INSTALL | Install a PHP version | websites.manage | manage | version (required: 7.4, 8.0 to 8.5) |
PHP_VERSION_REMOVE | Remove a PHP version (dangerous) | websites.manage | manage | version (required) |
PHPMYADMIN_SETUP | Set up phpMyAdmin | servers.manage | servers | port (1024 to 65535, default 8081), domain, certName |
PHPMYADMIN_REMOVE | Turn off phpMyAdmin | servers.manage | servers | None |
DNS_SETUP | Install and set up BIND for DNS zones | dns.manage | manage | None |
SYSTEM_LOGS | Read system logs (routine) | servers.logs | logs | source (required: journal, kernel, auth or cron), priority (emerg to debug, default debug), search (up to 200 characters), sinceMinutes (1 to 44640), lines (10 to 2000, default 300) |
SECURITY_STATUS | Read firewall, SSH, Fail2ban and update status (routine) | security.read | read | None |
SECURITY_TOOLS_INSTALL | Install security software | security.manage | servers | components (required, 1 to 3 of ufw, fail2ban, unattended-upgrades) |
A service is a systemd unit name: up to 100 letters, digits and : _ . @ -, starting with a letter or digit. The agent re-checks every operation against its own policy, so a job can still fail on the server: for example, SERVICE_STOP is refused (NOT_ALLOWED) for a service whose stop would cut off remote access, and a service the agent's configuration does not allow is refused too. Such errors arrive in the job's error, not as an HTTP status.
Other operations
The rest of the catalog is queued by the endpoints for what it changes, which build the parameters from the panel's own records. Queuing one directly answers 400 OPERATION_NOT_DIRECT. They appear in job lists and in GET /jobs/:id with these types.
| Area | Operations | Started by |
|---|---|---|
| Agent | AGENT_UPDATE | Update the agent, bulk actions |
| Websites | CREATE_SITE, CREATE_NGINX_CONFIG, DELETE_SITE, SITE_LOGS | Websites |
| SSL | ISSUE_SSL, INSTALL_SSL_CERT, RENEW_SSL, SET_SSL_RENEWAL | Websites |
| Files | FILE_LIST, FILE_READ, FILE_WRITE, FILE_MKDIR, FILE_RENAME, FILE_DELETE, FILE_UPLOAD, FILE_DOWNLOAD, FILE_CHMOD, FILE_EXTRACT, FILE_COMPRESS | Website files |
| Website Git deploy | SITE_GIT_SETUP, DEPLOY_SITE_GIT, ROLLBACK_SITE_GIT | Websites |
| Applications | CREATE_APPLICATION, DEPLOY_GIT, ROLLBACK_APPLICATION, CONFIGURE_APPLICATION, START_APPLICATION, STOP_APPLICATION, RESTART_APPLICATION, DELETE_APPLICATION, APP_STATUS, APP_LOGS | Applications |
| App installer | CMS_INSTALL, CMS_REMOVE | Applications |
| Databases | CREATE_DATABASE, DELETE_DATABASE, CREATE_DATABASE_USER, UPDATE_DATABASE_USER, DELETE_DATABASE_USER, DATABASE_TABLES, DATABASE_TABLE_ROWS, DATABASE_QUERY, PHPMYADMIN_SIGNON | Databases |
| DNS | DNS_ZONE_APPLY, DNS_ZONE_REMOVE | DNS |
MAIL_SETUP, MAIL_APPLY, MAIL_USAGE | ||
| Backups | CREATE_BACKUP, RESTORE_BACKUP, DELETE_BACKUP, UPLOAD_BACKUP, TEST_BACKUP_STORAGE | Backups |
| Cron | CREATE_CRON, DELETE_CRON, RUN_CRON | Cron jobs |
| Security | FIREWALL_ENABLE, FIREWALL_DISABLE, FIREWALL_RULE_ADD, FIREWALL_RULE_DELETE, FIREWALL_DEFAULTS, SSH_CONFIGURE, SSH_KEY_ADD, SSH_KEY_REMOVE, SSH_PORTS_SET, LOGIN_BANNER_SET, FAIL2BAN_CONFIGURE, FAIL2BAN_UNBAN, AUTO_UPDATES_CONFIGURE, SECURITY_UPDATES_INSTALL | Security |
| Containers | DOCKER_STATUS, DOCKER_INSTALL, CONTAINER_LIST, CONTAINER_INSPECT, CONTAINER_LOGS, CONTAINER_DEPLOY, CONTAINER_START, CONTAINER_STOP, CONTAINER_RESTART, CONTAINER_REMOVE, IMAGE_LIST, IMAGE_PULL, IMAGE_REMOVE | Containers |
| Assistant | LOCAL_AI_INSTALL, LOCAL_AI_REMOVE, LOCAL_AI_UNINSTALL | Assistant |
PLUGIN_INSTALL is in the catalog but not available in this release.
Servers
API reference for servers, enrollment tokens and agent install commands, metrics history, agent updates, terminal sessions and the dashboard summary.
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.