# Applications

URL: https://docs.vaultpanel.net/api-reference/applications

> API reference for Node.js, Python, Go and Ruby apps deployed from Git, their deployments, environment, scaling and push-to-deploy hooks, and the app installer.

An application is a Git repository the agent deploys into release folders on a server and runs under PM2, as the app's own Linux user. An app gets a domain and SSL through a linked reverse-proxy [website](https://docs.vaultpanel.net/api-reference/websites). See [Applications](https://docs.vaultpanel.net/guides/applications).

Hosting customers can use these endpoints for their own apps, within their plan.

## How changes work

Setting up, deploying, rolling back, starting, stopping, restarting, applying settings and deleting return `202 Accepted` with `{ application, job }` (deploys and rollbacks add `deployment`). The app's `status` is `creating`, `deploying`, `updating` or `deleting` while a job runs; another change meanwhile answers `409 APPLICATION_BUSY` with `details.jobId`.

Settings saved with [Update an application](https://docs.vaultpanel.net/api-reference/applications#update-an-application) are stored at once. Process settings (start command, port, health check, limits, copies, zero-downtime reloads) and environment variables go live on the next deploy or when you [apply](https://docs.vaultpanel.net/api-reference/applications#apply-settings); `configPending` says when saved settings are not live yet.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/applications` | [List applications](https://docs.vaultpanel.net/api-reference/applications#list-applications) |
| GET | `/api/v1/applications/suggest-port` | [Suggest a port](https://docs.vaultpanel.net/api-reference/applications#suggest-a-port) |
| POST | `/api/v1/applications` | [Create an application](https://docs.vaultpanel.net/api-reference/applications#create-an-application) |
| GET | `/api/v1/applications/:id` | [Get an application](https://docs.vaultpanel.net/api-reference/applications#get-an-application) |
| PATCH | `/api/v1/applications/:id` | [Update an application](https://docs.vaultpanel.net/api-reference/applications#update-an-application) |
| DELETE | `/api/v1/applications/:id` | [Delete an application](https://docs.vaultpanel.net/api-reference/applications#delete-an-application) |
| GET | `/api/v1/applications/:id/environment` | [Get environment variables](https://docs.vaultpanel.net/api-reference/applications#get-environment-variables) |
| PUT | `/api/v1/applications/:id/environment` | [Set environment variables](https://docs.vaultpanel.net/api-reference/applications#set-environment-variables) |
| POST | `/api/v1/applications/:id/deploy` | [Deploy](https://docs.vaultpanel.net/api-reference/applications#deploy) |
| POST | `/api/v1/applications/:id/rollback` | [Roll back](https://docs.vaultpanel.net/api-reference/applications#roll-back) |
| POST | `/api/v1/applications/:id/start` | [Start, stop or restart](https://docs.vaultpanel.net/api-reference/applications#start-stop-or-restart) |
| POST | `/api/v1/applications/:id/stop` | [Start, stop or restart](https://docs.vaultpanel.net/api-reference/applications#start-stop-or-restart) |
| POST | `/api/v1/applications/:id/restart` | [Start, stop or restart](https://docs.vaultpanel.net/api-reference/applications#start-stop-or-restart) |
| POST | `/api/v1/applications/:id/apply` | [Apply settings](https://docs.vaultpanel.net/api-reference/applications#apply-settings) |
| POST | `/api/v1/applications/:id/scale` | [Scale](https://docs.vaultpanel.net/api-reference/applications#scale) |
| POST | `/api/v1/applications/:id/status` | [Refresh process state](https://docs.vaultpanel.net/api-reference/applications#refresh-process-state) |
| POST | `/api/v1/applications/:id/logs` | [Read application logs](https://docs.vaultpanel.net/api-reference/applications#read-application-logs) |
| POST | `/api/v1/applications/:id/website` | [Add a website](https://docs.vaultpanel.net/api-reference/applications#add-a-website) |
| POST | `/api/v1/applications/:id/webhook` | [Turn push to deploy on](https://docs.vaultpanel.net/api-reference/applications#turn-push-to-deploy-on) |
| DELETE | `/api/v1/applications/:id/webhook` | [Turn push to deploy off](https://docs.vaultpanel.net/api-reference/applications#turn-push-to-deploy-off) |
| GET | `/api/v1/deployments` | [List deployments](https://docs.vaultpanel.net/api-reference/applications#list-deployments) |
| GET | `/api/v1/deployments/:id` | [Get a deployment](https://docs.vaultpanel.net/api-reference/applications#get-a-deployment) |
| POST | `/api/v1/hooks/deploy/:token` | [Git push hook](https://docs.vaultpanel.net/api-reference/applications#git-push-hook) |
| GET | `/api/v1/cms/apps` | [List installable apps](https://docs.vaultpanel.net/api-reference/applications#list-installable-apps) |
| GET | `/api/v1/cms/installs` | [List installed apps](https://docs.vaultpanel.net/api-reference/applications#list-installed-apps) |
| POST | `/api/v1/cms/installs` | [Install an app](https://docs.vaultpanel.net/api-reference/applications#install-an-app) |
| GET | `/api/v1/cms/installs/:id` | [Get an installed app](https://docs.vaultpanel.net/api-reference/applications#get-an-installed-app) |
| DELETE | `/api/v1/cms/installs/:id` | [Remove an installed app](https://docs.vaultpanel.net/api-reference/applications#remove-an-installed-app) |

## Runtimes

| `runtime` | Default start command | Notes |
| --- | --- | --- |
| `node` | `npm start` | Runs with the server's system-wide Node.js; dependencies installed with npm. Can run several copies and reload without downtime. |
| `python` | `gunicorn app:app` | Runs in its own virtual environment; dependencies from `requirements.txt`. |
| `go` | `./app` | Built with the server's Go (default build command `go build -o app .`). One process. Agent 0.32.0. |
| `ruby` | `bundle exec puma -b tcp://127.0.0.1:$PORT` | Gems from the Gemfile installed with Bundler into the release. One process. Agent 0.32.0. |

Deploying needs Git and PM2 on the server, plus the runtime itself for Python, Go and Ruby apps. The app's port reaches it as the `PORT` environment variable.

## The application object

```json
{
  "id": "5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c",
  "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "serverName": "web-1",
  "serverStatus": "online",
  "customerId": null,
  "name": "api",
  "runtime": "node",
  "repositoryUrl": "git@github.com:example/api.git",
  "branch": "main",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "startCommand": "node dist/server.js",
  "port": 3000,
  "keepReleases": 5,
  "healthCheckSeconds": 30,
  "cpuLimitPercent": null,
  "memoryLimitMb": 512,
  "instances": 2,
  "zeroDowntime": true,
  "status": "ready",
  "pendingAction": null,
  "provisioned": true,
  "current": { "deploymentId": "9e8d7c6b-…", "releaseId": "20261110113000-a1b2c3", "commit": "4e5f6a7b…", "deployedAt": "2026-11-10T11:30:42.000Z" },
  "configPending": false,
  "process": { "state": "running", "checkedAt": "2026-11-10T11:31:00.000Z" },
  "deployKey": "ssh-ed25519 AAAA… vaultpanel-api",
  "webhook": { "enabled": true, "signed": true, "createdAt": "2026-11-02T09:00:00.000Z" },
  "websiteId": "0b8e4c2a-…",
  "primaryDomain": "api.example.com",
  "website": null,
  "envKeys": null,
  "lastJobId": "…",
  "lastError": null,
  "createdAt": "2026-11-02T08:55:00.000Z",
  "updatedAt": "2026-11-10T11:30:42.000Z"
}
```

| Field | Description |
| --- | --- |
| `status` | `creating`, `ready`, `deploying`, `updating`, `deleting` or `failed`. |
| `current` | The live release, or `null` before the first deploy. |
| `process` | The last process state the agent reported (PM2), or `null`. |
| `deployKey` | The public key to add to the repository as a read-only deploy key, for private repositories over SSH. |
| `cpuLimitPercent`, `memoryLimitMb` | Resource caps, or `null` for none. CPU is a percentage of one core (10 to 6400); memory is in MiB (64 to 262144). |
| `instances` | Copies of the app that run, 1 to 16. |
| `website`, `envKeys` | Filled by [Get an application](https://docs.vaultpanel.net/api-reference/applications#get-an-application): the linked website and the names (not values) of the environment variables. |

## List applications

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

Apps, newest first. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Matches name, repository URL or domain. |
| `serverId` | string | No | Apps on one server. |
| `status` | string | No | One of the statuses above. |
| `runtime` | string | No | `node`, `python`, `go` or `ruby`. |
| `sort` | string | No | `createdAt` (default), `name` or `lastDeployedAt`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/applications?runtime=node" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.applications.list({ runtime: 'node' });
```

**Response** `200 OK`: `{ items: [application], pagination }`.

## Suggest a port

`GET /api/v1/applications/suggest-port` — Permission: applications.read — Token scope: read

A free port for a new app on a server. For staff, the first port from 3000 up that no app, website or customer holds, with `pool: null`. For a hosting customer, the first free port of their own, with their whole pool.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string | Yes | The server the app will run on. |

**Example request**

```bash
curl "https://panel.example.com/api/v1/applications/suggest-port?serverId=1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**Response** `200 OK`

```json
{ "success": true, "data": { "port": 3001, "pool": null }, "message": "OK", "requestId": "…" }
```

## Create an application

`POST /api/v1/applications` — Permission: applications.manage — Token scope: manage

Saves the app and queues `CREATE_APPLICATION`, which sets up its Linux user, folders and deploy key. With `domains`, it also creates the linked reverse-proxy website (needs `websites.manage`). With `deployNow` (the default), the first deployment is queued right after setup.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string | Yes | The server to run it on. |
| `name` | string | Yes | 3 to 32 lowercase letters, digits and dashes, starting with a letter. The Linux user and folder; unique per server among apps and websites. |
| `runtime` | string | Yes | `node`, `python`, `go` or `ruby`. |
| `repositoryUrl` | string | Yes | An `https://` or SSH Git URL, without a password in it. |
| `branch` | string | No | Default `main`. |
| `installCommand` | string | No | Up to 10 lines of up to 500 characters. |
| `buildCommand` | string | No | Same limits. |
| `startCommand` | string | No | One line. Defaults to the runtime's start command. |
| `port` | integer or null | With `domains` | 1024 to 65535; not 3306, 5432, 6379, 11211 or 27017. A hosting customer must use one of their own ports. |
| `keepReleases` | integer | No | Releases kept for rollbacks, 1 to 20. Default 5. |
| `healthCheckSeconds` | integer | No | How long a new release must stay up, 5 to 300. Default 30. |
| `domains` | string[] | No | Up to 20 domains for the linked website. |
| `env` | object[] | No | Up to 100 `{ key, value }`. `PORT`, `PATH`, `HOME`, `USER` and `PM2_HOME` are set by VaultPanel. |
| `deployNow` | boolean | No | Deploy once set up. Default `true`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
    "name": "api",
    "runtime": "node",
    "repositoryUrl": "https://github.com/example/api.git",
    "installCommand": "npm ci",
    "buildCommand": "npm run build",
    "startCommand": "node dist/server.js",
    "port": 3000,
    "domains": ["api.example.com"],
    "env": [{ "key": "NODE_ENV", "value": "production" }]
  }'
```

**JavaScript**

```js
const { application, job, deployment } = await panel.applications.create({
  serverId,
  name: 'api',
  runtime: 'node',
  repositoryUrl: 'https://github.com/example/api.git',
  installCommand: 'npm ci',
  buildCommand: 'npm run build',
  startCommand: 'node dist/server.js',
  port: 3000,
  domains: ['api.example.com'],
  env: [{ key: 'NODE_ENV', value: 'production' }],
});
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "application": { "id": "5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c", "name": "api", "status": "creating", "pendingAction": "create", "provisioned": false },
    "job": { "id": "…", "type": "CREATE_APPLICATION", "status": "queued" },
    "deployment": { "id": "9e8d7c6b-…", "kind": "deploy", "trigger": "manual", "status": "queued" }
  },
  "message": "App saved. The agent is setting it up on the server.",
  "requestId": "…"
}
```

`deployment` is `null` when `deployNow` is `false`. When the app is saved but its website could not be created, the app's `lastError` has code `WEBSITE_FAILED`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | `domains` without `websites.manage`. |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `SOFTWARE_MISSING` | Git, PM2 or the runtime is not installed (`details.missing`). |
| 409 | `NODE_IN_HOME_FOLDER` | Node.js is installed in a home folder (for example by nvm). Install it system-wide. |
| 409 | `AGENT_OUTDATED` | The agent is too old to run apps, or to run Go or Ruby apps. |
| 409 | `NGINX_NOT_INSTALLED` | `domains` given and NGINX is not installed. |
| 409 | `QUOTA_REACHED` | A hosting customer's plan allows no more apps. |
| 422 | `VALIDATION_ERROR` | A field is invalid, the name or port is taken, or `domains` without `port`. |

## Get an application

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

The app with its linked website, its environment variable names, its 10 most recent deployments (`deployments`) and change jobs (`recentJobs`).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const app = await panel.applications.get(appId);
```

**Response** `200 OK`: [the application object](https://docs.vaultpanel.net/api-reference/applications#the-application-object) with `deployments` and `recentJobs`.

## Update an application

`PATCH /api/v1/applications/:id` — Permission: applications.manage — Token scope: manage

Saves new settings at once. Repository and build settings apply on the next deploy; process settings apply on the next deploy or when you [apply](https://docs.vaultpanel.net/api-reference/applications#apply-settings). Send at least one field. A hosting customer's CPU and memory limits are capped by their plan.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `repositoryUrl`, `branch` | string | No | As for create. |
| `installCommand`, `buildCommand` | string or null | No | As for create; `null` removes it. |
| `startCommand` | string | No | One line. Cannot be empty. |
| `port` | integer or null | No | `null` runs the app without a port, unless it has a website. |
| `keepReleases`, `healthCheckSeconds` | integer | No | As for create. |
| `cpuLimitPercent` | integer or null | No | 10 to 6400 (percent of one core), or `null` for none. |
| `memoryLimitMb` | integer or null | No | 64 to 262144, or `null` for none. |
| `instances` | integer | No | 1 to 16 copies. More than one needs agent 0.14.0 and a Node.js or Python app. |
| `zeroDowntime` | boolean | No | Node.js apps: reload without downtime on deploys. Needs agent 0.32.0. |

**Example request**

**cURL**

```bash
curl -X PATCH https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"memoryLimitMb":512,"zeroDowntime":true}'
```

**JavaScript**

```js
const { application, changed } = await panel.applications.update(appId, { memoryLimitMb: 512, zeroDowntime: true });
```

**Response** `200 OK`

```json
{ "success": true, "data": { "application": { "id": "5c4b3a29-…", "configPending": true }, "changed": ["memoryLimitMb", "zeroDowntime"] }, "message": "Settings saved", "requestId": "…" }
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_BUSY` | Another change is running. |
| 409 | `AGENT_OUTDATED` | Several copies or zero-downtime reloads need a newer agent. |
| 422 | `VALIDATION_ERROR` | An invalid value, a port in use, several copies of a Go or Ruby app, zero-downtime on another runtime, or nothing to update. |

## Delete an application

`DELETE /api/v1/applications/:id` — Permission: applications.manage — Token scope: manage

Stops the app and removes it from PM2 (`DELETE_APPLICATION`), and deletes its linked website too (needs `websites.manage`).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `removeFiles` | boolean | No | Also delete its releases, folder and Linux user. Default `false`. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c?removeFiles=true" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.applications.remove(appId, { removeFiles: true });
```

**Response** `202 Accepted` with `{ application, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | The app has a website and you lack `websites.manage`. |
| 409 | `APPLICATION_BUSY` | Another change is running. |

## Get environment variables

`GET /api/v1/applications/:id/environment` — Permission: applications.manage — Token scope: manage

The app's environment variables, with their values. Every read is recorded in the audit log.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/environment \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { variables } = await panel.applications.environment(appId);
```

**Response** `200 OK`

```json
{ "success": true, "data": { "variables": [{ "key": "NODE_ENV", "value": "production" }] }, "message": "OK", "requestId": "…" }
```

## Set environment variables

`PUT /api/v1/applications/:id/environment` — Permission: applications.manage — Token scope: manage

Replaces the whole list. The new values go live on the next deploy or when you [apply](https://docs.vaultpanel.net/api-reference/applications#apply-settings). The audit log records which names were added, changed and removed, never the values.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `variables` | object[] | Yes | Up to 100 `{ key, value }`. Keys are letters, digits and underscores, not starting with a digit, each once; values up to 8192 characters. `PORT`, `PATH`, `HOME`, `USER` and `PM2_HOME` are reserved. |

**Example request**

**cURL**

```bash
curl -X PUT https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/environment \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"variables":[{"key":"NODE_ENV","value":"production"},{"key":"LOG_LEVEL","value":"info"}]}'
```

**JavaScript**

```js
await panel.applications.setEnvironment(appId, {
  variables: [
    { key: 'NODE_ENV', value: 'production' },
    { key: 'LOG_LEVEL', value: 'info' },
  ],
});
await panel.applications.apply(appId);
```

**Response** `200 OK` with `{ application }`, message `Environment saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_BUSY` | Another change is running. |
| 422 | `VALIDATION_ERROR` | An invalid, reserved or repeated key, or a value too long (`details` names `variables.N.key`…). |

## Deploy

`POST /api/v1/applications/:id/deploy` — Permission: applications.deploy — Token scope: deploy

Deploys the newest commit of the branch (`DEPLOY_GIT`): clone it into a new release folder, run the install and build commands, point `current` at the release, restart and wait for the port to answer (the health check). A deployment that fails before the switch leaves the running release untouched; one that fails its health check is switched back to the previous release. Also sets up an app whose setup failed.

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/deploy \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { job, deployment } = await panel.applications.deploy(appId);
const { job: done } = await panel.jobs.wait(job.id);
if (done.status !== 'succeeded') throw new Error(done.error?.message);
```

**Response** `202 Accepted` with `{ application, deployment, job }`, message `Deploying the app`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_BUSY` | Another change is running. |
| 409 | `APPLICATION_NOT_READY` | The app is still being set up. |
| 409 | `SERVER_NOT_READY`, `SOFTWARE_MISSING`, `AGENT_OUTDATED`, `NODE_IN_HOME_FOLDER` | As for create. |

## Roll back

`POST /api/v1/applications/:id/rollback` — Permission: applications.deploy — Token scope: deploy

Makes an earlier release live again (`ROLLBACK_APPLICATION`) without building it again. Only the newest `keepReleases` releases are kept on the server.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deploymentId` | string | Yes | A successful deployment of this app whose release is still on the server. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/rollback \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"deploymentId":"9e8d7c6b-5a49-4382-9170-8f7e6d5c4b3a"}'
```

**JavaScript**

```js
const { job } = await panel.applications.rollback(appId, { deploymentId });
```

**Response** `202 Accepted` with `{ application, deployment, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such deployment of this app. |
| 409 | `APPLICATION_NOT_DEPLOYED` | The app has never been deployed. |
| 409 | `RELEASE_ALREADY_LIVE` | That release is already live. |
| 409 | `RELEASE_NOT_DEPLOYABLE` | That deployment did not succeed. |
| 409 | `RELEASE_NOT_FOUND` | Its release was removed from the server. Deploy its commit again instead. |

## Start, stop or restart

`POST /api/v1/applications/:id/:action` — Permission: applications.deploy — Token scope: deploy

`action` is `start`, `stop` or `restart`. Works on a deployed app.

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/restart \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.applications.restart(appId);
```

**Response** `202 Accepted` with `{ application, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_NOT_DEPLOYED` | Deploy the app first. |
| 409 | `APPLICATION_BUSY`, `APPLICATION_NOT_READY` | See above. |

## Apply settings

`POST /api/v1/applications/:id/apply` — Permission: applications.manage — Token scope: manage

Writes the saved process settings and environment to the server and restarts the app with them (`CONFIGURE_APPLICATION`), without deploying.

**Response** `202 Accepted` with `{ application, job }`. Errors as for [Start, stop or restart](https://docs.vaultpanel.net/api-reference/applications#start-stop-or-restart).

## Scale

`POST /api/v1/applications/:id/scale` — Permission: applications.manage — Token scope: manage

Sets how many copies of the app run and puts it into effect: a running app changes now, in place, while the other copies keep serving. A stopped or undeployed app uses the new count the next time it starts. See [Scaling](https://docs.vaultpanel.net/guides/applications/scaling).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `instances` | integer | Yes | 1 to 16. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/scale \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" -d '{"instances":4}'
```

**JavaScript**

```js
await panel.applications.scale(appId, 4);
```

**Response** `202 Accepted` with `{ application, job }` when a running app changes, or `200 OK` with `job: null` when the count is saved for later.

**Errors** as for [Update an application](https://docs.vaultpanel.net/api-reference/applications#update-an-application).

## Refresh process state

`POST /api/v1/applications/:id/status` — Permission: applications.read — Token scope: read

Queues a routine `APP_STATUS` job that reads the app's process state from PM2. The app's `process` is updated when it finishes.

**Response** `202 Accepted` with the job.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_NOT_READY` | The app is not set up on its server yet. |

## Read application logs

`POST /api/v1/applications/:id/logs` — Permission: applications.logs — Token scope: logs

Queues a routine `APP_LOGS` job that reads the last lines of the app's output or error log. The lines arrive in the job's `output`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `log` | string | Yes | `output` or `error`. |
| `lines` | integer | No | 10 to 2000. Default 200. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/logs \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" -d '{"log":"error","lines":200}'
```

**JavaScript**

```js
const job = await panel.applications.logs(appId, { log: 'error', lines: 200 });
const { job: done } = await panel.jobs.wait(job.id);
```

**Response** `202 Accepted` with the job.

## Add a website

`POST /api/v1/applications/:id/website` — Permission: applications.manage, websites.manage — Token scope: manage

Gives an app without a website one: a reverse proxy from the domains to the app's port. Then [issue a certificate](https://docs.vaultpanel.net/api-reference/websites#issue-a-lets-encrypt-certificate) on the new website.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | string[] | Yes | 1 to 20 domains. |

**Response** `202 Accepted` with `{ application, website, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `APPLICATION_HAS_WEBSITE` | The app already has a website. Add domains to that website instead. |
| 422 | `VALIDATION_ERROR` | The app has no port, or a domain is invalid or taken. |

## Turn push to deploy on

`POST /api/v1/applications/:id/webhook` — Permission: applications.manage — Token scope: manage

Creates (or replaces) the app's push webhook and returns its URL and signing secret, shown only this once. Add both to your Git host as a push webhook with content type `application/json`; pushes to the app's branch then deploy it through the [Git push hook](https://docs.vaultpanel.net/api-reference/applications#git-push-hook).

**Example request**

```bash
curl -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/webhook \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "application": { "id": "5c4b3a29-…", "webhook": { "enabled": true, "signed": true, "createdAt": "2026-11-10T11:40:00.000Z" } },
    "webhook": { "url": "https://panel.example.com/api/v1/hooks/deploy/…", "secret": "…" }
  },
  "message": "Copy the webhook URL now: it is shown only once",
  "requestId": "…"
}
```

## Turn push to deploy off

`DELETE /api/v1/applications/:id/webhook` — Permission: applications.manage — Token scope: manage

**Response** `200 OK` with `{ application }`, message `Push to deploy turned off`.

## List deployments

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

App deployments and rollbacks across all apps, newest first. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `applicationId` | string | No | Deployments of one app. |
| `serverId` | string | No | Deployments on one server. |
| `status` | string | No | `running`, `succeeded`, `failed` or `cancelled`. `running` also matches deployments still queued. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/deployments?applicationId=5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.deployments.list({ applicationId: appId });
```

**Response** `200 OK`: `{ items: [deployment], pagination }`.

## Get a deployment

`GET /api/v1/deployments/:id` — Permission: applications.read — Token scope: read

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/deployments/9e8d7c6b-5a49-4382-9170-8f7e6d5c4b3a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const deployment = await panel.deployments.get(deploymentId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "id": "9e8d7c6b-5a49-4382-9170-8f7e6d5c4b3a",
    "applicationId": "5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c",
    "applicationName": "api",
    "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
    "serverName": "web-1",
    "jobId": "…",
    "kind": "deploy",
    "trigger": "webhook",
    "status": "succeeded",
    "releaseId": "20261110113000-a1b2c3",
    "sourceDeploymentId": null,
    "repositoryUrl": "git@github.com:example/api.git",
    "branch": "main",
    "commit": { "hash": "4e5f6a7b…", "message": "Add rate limiting", "author": "Ada Lovelace" },
    "failedStage": null,
    "error": null,
    "releaseAvailable": true,
    "isCurrent": true,
    "stages": null,
    "requestedBy": null,
    "startedAt": "2026-11-10T11:30:00.000Z",
    "finishedAt": "2026-11-10T11:30:42.000Z",
    "durationMs": 42000,
    "createdAt": "2026-11-10T11:30:00.000Z"
  },
  "message": "OK",
  "requestId": "…"
}
```

`kind` is `deploy` or `rollback`; `trigger` says what started it, such as `manual` or `webhook`. `stages` comes from the job's output, and the deployment's log is its job's log: read it with [`GET /jobs/:id`](https://docs.vaultpanel.net/api-reference/jobs#get-a-job-and-its-logs).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such deployment. |

## Git push hook

`POST /api/v1/hooks/deploy/:token` — Auth: hook

The URL Git hosts call on a push, for both apps and [Git-deployed websites](https://docs.vaultpanel.net/api-reference/websites#turn-push-to-deploy-on-or-off). No session or API token: the secret token in the URL finds the app or website, and the request must be signed with the webhook's secret.

| Git host | Signature |
| --- | --- |
| GitHub, Gitea, Forgejo, Bitbucket | HMAC-SHA256 of the raw body with the secret, in `X-Hub-Signature-256` (`sha256=<hex>`), `X-Gitea-Signature` or `X-Forgejo-Signature` (`<hex>`), or `X-Hub-Signature` (`sha256=<hex>`). |
| GitLab | The secret itself, in `X-Gitlab-Token`. |

Only pushes to the configured branch deploy. Other events (named in `X-GitHub-Event`, `X-Gitlab-Event`, `X-Gitea-Event` or `X-Event-Key`), pings and pushes to other branches answer `200` with `ignored: true` and a reason. Limited to 30 requests a minute per address. Webhooks made before signing existed have no secret and work on the URL alone.

**Example request**

```bash
BODY='{"ref":"refs/heads/main"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | sed 's/^.* //')
curl https://panel.example.com/api/v1/hooks/deploy/$WEBHOOK_TOKEN \
  -H "Content-Type: application/json" -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=$SIG" -d "$BODY"
```

**Response** `202 Accepted`

```json
{ "success": true, "data": { "ignored": false, "deploymentId": "9e8d7c6b-…", "releaseId": "20261110113000-a1b2c3" }, "message": "Deploying", "requestId": "…" }
```

**Response** `200 OK`, ignored

```json
{ "success": true, "data": { "ignored": true, "reason": "Push to refs/heads/dev; this app deploys main" }, "message": "Push to refs/heads/dev; this app deploys main", "requestId": "…" }
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 401 | `WEBHOOK_SIGNATURE_INVALID` | The signature is missing or does not match. The rejection is audited. |
| 404 | `NOT_FOUND` | Unknown webhook token. |
| 409 | `APPLICATION_BUSY`, `WEBSITE_BUSY` | A change is already running. |
| 429 | `RATE_LIMITED` | More than 30 calls a minute from this address. |

## The app installer

The app installer puts WordPress, Joomla, Drupal or Laravel into a PHP website in one step, with its own database and user. See [App installer](https://docs.vaultpanel.net/guides/websites/cms-installer).

| `app` | Installs into | Minimum PHP | Admin page |
| --- | --- | --- | --- |
| `wordpress` | A folder of the document root, or the root | 7.4 | `wp-admin/` |
| `joomla` | A folder of the document root, or the root | 8.1 | `administrator/` |
| `drupal` | A project folder (default `drupal`); the site serves its `web` folder | 8.1 | `user/login` |
| `laravel` | A project folder (default `laravel`); the site serves its `public` folder | 8.2 | None |

Drupal and Laravel take over the website's document root: they need a website with no other installed app, and a website with one of them takes no other. Needs agent 0.20.0.

## List installable apps

`GET /api/v1/cms/apps`

The catalog above, with each app's description and where it is downloaded from. Any signed-in caller may read it.

**Example request**

**cURL**

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

**JavaScript**

```js
const { apps } = await panel.cms.catalog();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "apps": [
      {
        "key": "wordpress",
        "label": "WordPress",
        "description": "Blogs and websites. The most used CMS.",
        "kind": "docroot",
        "minPhp": "7.4",
        "admin": true,
        "adminPath": "wp-admin/",
        "source": "wordpress.org, checked against its published SHA-1"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## List installed apps

`GET /api/v1/cms/installs` — Permission: websites.read — Token scope: read

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | No | Apps in one website. |
| `serverId` | string | No | Apps on one server. |
| `page`, `pageSize` | integer | No | Paging. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/cms/installs?websiteId=0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.cms.installs({ websiteId });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "2a3b4c5d-…",
        "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
        "serverName": "web-1",
        "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
        "websiteName": "shop",
        "websiteDomain": "shop.example.com",
        "customerId": null,
        "app": "wordpress",
        "appLabel": "WordPress",
        "kind": "docroot",
        "version": "6.8.3",
        "directory": "public/blog",
        "path": "blog",
        "url": "https://shop.example.com/blog",
        "adminUrl": "https://shop.example.com/blog/wp-admin/",
        "title": "Shop blog",
        "adminUser": "admin",
        "adminEmail": "ada@example.com",
        "database": { "id": "…", "name": "shop_wp" },
        "databaseUser": { "id": "…", "username": "shop_wp" },
        "status": "installed",
        "lastJobId": "…",
        "lastError": null,
        "installedAt": "2026-11-05T15:02:00.000Z",
        "createdAt": "2026-11-05T15:00:00.000Z",
        "updatedAt": "2026-11-05T15:02:00.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}
```

`status` is `waiting`, `installing`, `installed`, `removing` or `failed`.

## Install an app

`POST /api/v1/cms/installs` — Permission: websites.manage, databases.manage — Token scope: manage

Installs an app into an existing PHP website, or into a new one created with it. A database and a database user are created for it. The admin password is generated when you leave it out, and returned only in this response: the panel does not keep it.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `app` | string | Yes | `wordpress`, `joomla`, `drupal` or `laravel`. |
| `websiteId` | string | One of the two | An existing PHP website. |
| `newWebsite` | object | One of the two | `{ serverId, name, domains, phpVersion }` for a new PHP website. |
| `path` | string | No | A folder of the document root (WordPress, Joomla) or the project folder (Drupal, Laravel). Lowercase letters, digits, dots, dashes and underscores, up to three folders deep. Empty installs at the site's root. |
| `title` | string | No | The site title, up to 100 characters. |
| `adminUser` | string | No | 3 to 60 letters, digits, dots, dashes and underscores. |
| `adminEmail` | string | No | The admin's email address. |
| `adminPassword` | string | No | 12 to 128 characters without spaces. Generated when left out. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/cms/installs \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"app":"wordpress","websiteId":"0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a","path":"blog","title":"Shop blog","adminEmail":"ada@example.com"}'
```

**JavaScript**

```js
const { install, admin } = await panel.cms.install({
  app: 'wordpress',
  websiteId,
  path: 'blog',
  title: 'Shop blog',
  adminEmail: 'ada@example.com',
});
console.log(admin.url, admin.username, admin.password);
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "install": { "id": "2a3b4c5d-…", "app": "wordpress", "status": "waiting", "url": "https://shop.example.com/blog" },
    "admin": { "url": "https://shop.example.com/blog/wp-admin/", "username": "admin", "password": "…", "email": "ada@example.com" },
    "database": { "name": "shop_wp", "username": "shop_wp" },
    "jobs": { "website": null, "database": { "id": "…", "type": "CREATE_DATABASE", "status": "queued" } }
  },
  "message": "Installing the app",
  "requestId": "…"
}
```

`admin` is `null` for Laravel, which has no admin page. `jobs.website` is the new website's job when `newWebsite` was given.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | You lack `websites.manage` or `databases.manage`. |
| 409 | `WEBSITE_NOT_READY` | The website is not ready yet. |
| 409 | `PANEL_WEBSITE` | The website serves VaultPanel itself. |
| 409 | `WEBSITE_OWNED_BY_APP` | The website serves an app. |
| 409 | `CMS_PHP_TOO_OLD` | The website's PHP version is older than the app needs. |
| 409 | `CMS_SITE_TAKEN` | A Drupal or Laravel app already uses the document root, or Drupal or Laravel would take over a website that already has an app. |
| 409 | `AGENT_OUTDATED` | The agent is older than 0.20.0. |
| 409 | `QUOTA_REACHED` | A hosting customer's plan allows no more websites, databases or database users. |
| 422 | `VALIDATION_ERROR` | Not exactly one of `websiteId` and `newWebsite`, or an invalid field. |

## Get an installed app

`GET /api/v1/cms/installs/:id` — Permission: websites.read — Token scope: read

**Response** `200 OK` with the installed app, as in [List installed apps](https://docs.vaultpanel.net/api-reference/applications#list-installed-apps). `404 NOT_FOUND` when there is no such install.

## Remove an installed app

`DELETE /api/v1/cms/installs/:id` — Permission: websites.manage — Token scope: manage

Removes the app's files from the website (`CMS_REMOVE`). The website stays.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `removeDatabase` | boolean | No | Also delete its database and database user (needs `databases.manage`). Default `false`. |

**Example request**

**cURL**

```bash
curl -X DELETE "https://panel.example.com/api/v1/cms/installs/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d?removeDatabase=true" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { warnings } = await panel.cms.remove(installId, { removeDatabase: true });
```

**Response** `202 Accepted` with `{ install, job, warnings }`. `warnings` lists anything that could not be removed, such as the database.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `CMS_BUSY` | The app is still being installed, or already being removed. |
