# Jobs

URL: https://docs.vaultpanel.net/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.

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](https://docs.vaultpanel.net/getting-started/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](https://docs.vaultpanel.net/api-reference/jobs#queue-an-operation).

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/jobs` | [List jobs](https://docs.vaultpanel.net/api-reference/jobs#list-jobs) |
| GET | `/api/v1/jobs/:id` | [Get a job and its logs](https://docs.vaultpanel.net/api-reference/jobs#get-a-job-and-its-logs) |
| POST | `/api/v1/jobs/:id/cancel` | [Cancel a job](https://docs.vaultpanel.net/api-reference/jobs#cancel-a-job) |
| GET | `/api/v1/jobs/operations` | [List operations](https://docs.vaultpanel.net/api-reference/jobs#list-operations) |
| POST | `/api/v1/servers/:id/jobs` | [Queue an operation](https://docs.vaultpanel.net/api-reference/jobs#queue-an-operation) |

## Job lifecycle

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

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

`GET /api/v1/jobs` — Permission: jobs.read — Token scope: read

Jobs, newest first. Hosting customers see only jobs on their own records. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**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**

```bash
curl "https://panel.example.com/api/v1/jobs?status=failed&pageSize=10" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `afterLogId` | integer | No | Only log lines with a higher id. Default `0`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/jobs/a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d?afterLogId=0" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

```json
{
  "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](https://docs.vaultpanel.net/api-reference/jobs#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

`POST /api/v1/jobs/:id/cancel` — 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**

```bash
curl -X POST https://panel.example.com/api/v1/jobs/a1d3c5e7-2b4d-4f6a-8c0e-1f3a5c7e9b2d/cancel \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

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

`GET /api/v1/jobs/operations`

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**

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

**JavaScript**

```js
const { items } = await panel.jobs.operations();
```

**Response** `200 OK`

```json
{
  "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` — Permission: per operation

Queues one of the [direct operations](https://docs.vaultpanel.net/api-reference/jobs#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**

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

**JavaScript**

```js
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](https://docs.vaultpanel.net/api-reference/jobs#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](https://docs.vaultpanel.net/api-reference/jobs#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](https://docs.vaultpanel.net/guides/servers/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](https://docs.vaultpanel.net/guides/dns-and-email/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](https://docs.vaultpanel.net/api-reference/servers#update-the-agent), bulk actions |
| Websites | `CREATE_SITE`, `CREATE_NGINX_CONFIG`, `DELETE_SITE`, `SITE_LOGS` | [Websites](https://docs.vaultpanel.net/api-reference/websites) |
| SSL | `ISSUE_SSL`, `INSTALL_SSL_CERT`, `RENEW_SSL`, `SET_SSL_RENEWAL` | [Websites](https://docs.vaultpanel.net/api-reference/websites#issue-a-lets-encrypt-certificate) |
| 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](https://docs.vaultpanel.net/api-reference/websites#run-a-file-action) |
| Website Git deploy | `SITE_GIT_SETUP`, `DEPLOY_SITE_GIT`, `ROLLBACK_SITE_GIT` | [Websites](https://docs.vaultpanel.net/api-reference/websites#set-up-git-deploy) |
| Applications | `CREATE_APPLICATION`, `DEPLOY_GIT`, `ROLLBACK_APPLICATION`, `CONFIGURE_APPLICATION`, `START_APPLICATION`, `STOP_APPLICATION`, `RESTART_APPLICATION`, `DELETE_APPLICATION`, `APP_STATUS`, `APP_LOGS` | [Applications](https://docs.vaultpanel.net/api-reference/applications) |
| App installer | `CMS_INSTALL`, `CMS_REMOVE` | [Applications](https://docs.vaultpanel.net/api-reference/applications#install-an-app) |
| Databases | `CREATE_DATABASE`, `DELETE_DATABASE`, `CREATE_DATABASE_USER`, `UPDATE_DATABASE_USER`, `DELETE_DATABASE_USER`, `DATABASE_TABLES`, `DATABASE_TABLE_ROWS`, `DATABASE_QUERY`, `PHPMYADMIN_SIGNON` | [Databases](https://docs.vaultpanel.net/api-reference/databases) |
| DNS | `DNS_ZONE_APPLY`, `DNS_ZONE_REMOVE` | [DNS](https://docs.vaultpanel.net/api-reference/dns) |
| Email | `MAIL_SETUP`, `MAIL_APPLY`, `MAIL_USAGE` | [Mail](https://docs.vaultpanel.net/api-reference/mail) |
| Backups | `CREATE_BACKUP`, `RESTORE_BACKUP`, `DELETE_BACKUP`, `UPLOAD_BACKUP`, `TEST_BACKUP_STORAGE` | [Backups](https://docs.vaultpanel.net/api-reference/backups) |
| Cron | `CREATE_CRON`, `DELETE_CRON`, `RUN_CRON` | [Cron jobs](https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/api-reference/containers) |
| Assistant | `LOCAL_AI_INSTALL`, `LOCAL_AI_REMOVE`, `LOCAL_AI_UNINSTALL` | [Assistant](https://docs.vaultpanel.net/api-reference/assistant) |

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