API Reference

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.

Last updated

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

MethodPathDescription
GET/api/v1/jobsList jobs
GET/api/v1/jobs/:idGet a job and its logs
POST/api/v1/jobs/:id/cancelCancel a job
GET/api/v1/jobs/operationsList operations
POST/api/v1/servers/:id/jobsQueue an operation

Job lifecycle

queued ──> dispatched ──> running ──> succeeded
   │                         ├──────> failed
   │                         └──────> timed_out
   └──> cancelled (only while queued)
StatusMeaning
queuedWaiting for the agent to pick it up. A job no agent picks up within 5 minutes fails.
dispatchedHanded to the agent, not started yet.
runningThe agent is carrying it out and streaming its log.
succeeded, failed, timed_out, cancelledFinal.

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"
}
FieldDescription
resourceThe record the job acts on, such as { "type": "website", "id": "…" }, or null.
requestedByThe person who queued it, or { "type": "system" } for the panel's own work. A hosting customer sees their provider's staff as { "type": "staff" }.
outputWhat the operation returned. Its shape depends on the operation.
error{ code, message } when the job failed.
expiresAtWhen a queued job fails if no agent has picked it up.

List jobs

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

Jobs, newest first. Hosting customers see only jobs on their own records. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
serverIdstringNoJobs on one server.
statusstringNoOne of the statuses above.
typestringNoOne operation, such as DEPLOY_GIT. Routine jobs of that type are included.
includeRoutinebooleanNoInclude routine jobs. Default false.
sortstringNocreatedAt (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

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

The 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

NameTypeRequiredDescription
afterLogIdintegerNoOnly 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

StatusCodeWhen
404NOT_FOUNDNo such job, or not one of yours (hosting customers).

Cancel a job

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

Cancels 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

StatusCodeWhen
404NOT_FOUNDNo such job.
409JOB_NOT_CANCELLABLEThe job is no longer queued.

List operations

GET/api/v1/jobs/operations
Auth
Session cookie (+ CSRF token) or API token

The 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

POST/api/v1/servers/:id/jobs
Auth
Session cookie (+ CSRF token) or API token
Permission
per operation

Queues 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

FieldTypeRequiredDescription
typestringYesThe operation, such as SERVICE_RESTART.
paramsobjectNoThe 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

StatusCodeWhen
400OPERATION_NOT_DIRECTThe operation is started by its own endpoint (websites, files, apps…), not directly.
403FORBIDDENYou lack the operation's permission, or you are a hosting customer.
404NOT_FOUNDNo such server.
409OPERATION_UNAVAILABLEThe operation is in the catalog but not available in this release.
409SERVER_NOT_READYThe server has no connected agent yet.
409AGENT_OUTDATEDThe server's agent does not support this operation. Update the agent.
409DUPLICATE_OPERATIONThe same operation is already queued or running (details.jobId).
422VALIDATION_ERRORUnknown 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.

OperationWhat it doesPermissionToken scopeParameters
SERVICE_STATUSCheck a systemd service's stateservers.servicesserversservice (required)
SERVICE_STARTStart a serviceservers.servicesserversservice (required)
SERVICE_STOPStop a service (dangerous)servers.servicesserversservice (required)
SERVICE_RESTARTRestart a service (dangerous)servers.servicesserversservice (required)
SERVICE_LOGSRead a service's journalservers.servicesserversservice (required), lines (10 to 1000, default 200)
PROCESS_LISTList running processesservers.processesserverslimit (1 to 500, default 50), sortBy (cpu or memory, default cpu)
PROCESS_SIGNALStop a process (dangerous)servers.signalserverspid (required, 2 to 4194304), command (required, the process name you saw), signal (TERM or KILL, default TERM)
LISTENING_PORTSList listening ports (routine)servers.processesserversNone
SELF_CHECKRun the server self-check now (routine)servers.readreadNone
SERVER_REBOOTReboot the server (dangerous)servers.rebootserversNone
WEB_STACK_INSTALLInstall server softwarewebsites.managemanagecomponents (required, 1 to 12 of nginx, php, certbot, apache, git, pm2, python, go, ruby, composer, mariadb, cron)
PHP_VERSION_INSTALLInstall a PHP versionwebsites.managemanageversion (required: 7.4, 8.0 to 8.5)
PHP_VERSION_REMOVERemove a PHP version (dangerous)websites.managemanageversion (required)
PHPMYADMIN_SETUPSet up phpMyAdminservers.manageserversport (1024 to 65535, default 8081), domain, certName
PHPMYADMIN_REMOVETurn off phpMyAdminservers.manageserversNone
DNS_SETUPInstall and set up BIND for DNS zonesdns.managemanageNone
SYSTEM_LOGSRead system logs (routine)servers.logslogssource (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_STATUSRead firewall, SSH, Fail2ban and update status (routine)security.readreadNone
SECURITY_TOOLS_INSTALLInstall security softwaresecurity.manageserverscomponents (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.

AreaOperationsStarted by
AgentAGENT_UPDATEUpdate the agent, bulk actions
WebsitesCREATE_SITE, CREATE_NGINX_CONFIG, DELETE_SITE, SITE_LOGSWebsites
SSLISSUE_SSL, INSTALL_SSL_CERT, RENEW_SSL, SET_SSL_RENEWALWebsites
FilesFILE_LIST, FILE_READ, FILE_WRITE, FILE_MKDIR, FILE_RENAME, FILE_DELETE, FILE_UPLOAD, FILE_DOWNLOAD, FILE_CHMOD, FILE_EXTRACT, FILE_COMPRESSWebsite files
Website Git deploySITE_GIT_SETUP, DEPLOY_SITE_GIT, ROLLBACK_SITE_GITWebsites
ApplicationsCREATE_APPLICATION, DEPLOY_GIT, ROLLBACK_APPLICATION, CONFIGURE_APPLICATION, START_APPLICATION, STOP_APPLICATION, RESTART_APPLICATION, DELETE_APPLICATION, APP_STATUS, APP_LOGSApplications
App installerCMS_INSTALL, CMS_REMOVEApplications
DatabasesCREATE_DATABASE, DELETE_DATABASE, CREATE_DATABASE_USER, UPDATE_DATABASE_USER, DELETE_DATABASE_USER, DATABASE_TABLES, DATABASE_TABLE_ROWS, DATABASE_QUERY, PHPMYADMIN_SIGNONDatabases
DNSDNS_ZONE_APPLY, DNS_ZONE_REMOVEDNS
EmailMAIL_SETUP, MAIL_APPLY, MAIL_USAGEMail
BackupsCREATE_BACKUP, RESTORE_BACKUP, DELETE_BACKUP, UPLOAD_BACKUP, TEST_BACKUP_STORAGEBackups
CronCREATE_CRON, DELETE_CRON, RUN_CRONCron jobs
SecurityFIREWALL_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_INSTALLSecurity
ContainersDOCKER_STATUS, DOCKER_INSTALL, CONTAINER_LIST, CONTAINER_INSPECT, CONTAINER_LOGS, CONTAINER_DEPLOY, CONTAINER_START, CONTAINER_STOP, CONTAINER_RESTART, CONTAINER_REMOVE, IMAGE_LIST, IMAGE_PULL, IMAGE_REMOVEContainers
AssistantLOCAL_AI_INSTALL, LOCAL_AI_REMOVE, LOCAL_AI_UNINSTALLAssistant

PLUGIN_INSTALL is in the catalog but not available in this release.