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. See 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 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; configPending says when saved settings are not live yet.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/applications | List applications |
| GET | /api/v1/applications/suggest-port | Suggest a port |
| POST | /api/v1/applications | Create an application |
| GET | /api/v1/applications/:id | Get an application |
| PATCH | /api/v1/applications/:id | Update an application |
| DELETE | /api/v1/applications/:id | Delete an application |
| GET | /api/v1/applications/:id/environment | Get environment variables |
| PUT | /api/v1/applications/:id/environment | Set environment variables |
| POST | /api/v1/applications/:id/deploy | Deploy |
| POST | /api/v1/applications/:id/rollback | Roll back |
| POST | /api/v1/applications/:id/start | Start, stop or restart |
| POST | /api/v1/applications/:id/stop | Start, stop or restart |
| POST | /api/v1/applications/:id/restart | Start, stop or restart |
| POST | /api/v1/applications/:id/apply | Apply settings |
| POST | /api/v1/applications/:id/scale | Scale |
| POST | /api/v1/applications/:id/status | Refresh process state |
| POST | /api/v1/applications/:id/logs | Read application logs |
| POST | /api/v1/applications/:id/website | Add a website |
| POST | /api/v1/applications/:id/webhook | Turn push to deploy on |
| DELETE | /api/v1/applications/:id/webhook | Turn push to deploy off |
| GET | /api/v1/deployments | List deployments |
| GET | /api/v1/deployments/:id | Get a deployment |
| POST | /api/v1/hooks/deploy/:token | Git push hook |
| GET | /api/v1/cms/apps | List installable apps |
| GET | /api/v1/cms/installs | List installed apps |
| POST | /api/v1/cms/installs | Install an app |
| GET | /api/v1/cms/installs/:id | Get an installed app |
| DELETE | /api/v1/cms/installs/:id | 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
{
"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: the linked website and the names (not values) of the environment variables. |
List applications
/api/v1/applicationsApps, newest first. Supports the list parameters.
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 "https://panel.example.com/api/v1/applications?runtime=node" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.applications.list({ runtime: 'node' });Response 200 OK: { items: [application], pagination }.
Suggest a port
/api/v1/applications/suggest-portA 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
curl "https://panel.example.com/api/v1/applications/suggest-port?serverId=1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"Response 200 OK
{ "success": true, "data": { "port": 3001, "pool": null }, "message": "OK", "requestId": "…" }Create an application
/api/v1/applicationsSaves 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 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" }]
}'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
{
"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
/api/v1/applications/:idThe app with its linked website, its environment variable names, its 10 most recent deployments (deployments) and change jobs (recentJobs).
Example request
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const app = await panel.applications.get(appId);Response 200 OK: the application object with deployments and recentJobs.
Update an application
/api/v1/applications/:idSaves new settings at once. Repository and build settings apply on the next deploy; process settings apply on the next deploy or when you apply. 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 -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}'const { application, changed } = await panel.applications.update(appId, { memoryLimitMb: 512, zeroDowntime: true });Response 200 OK
{ "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
/api/v1/applications/:idStops 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 -X DELETE "https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c?removeFiles=true" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/applications/:id/environmentThe app's environment variables, with their values. Every read is recorded in the audit log.
Example request
curl https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/environment \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { variables } = await panel.applications.environment(appId);Response 200 OK
{ "success": true, "data": { "variables": [{ "key": "NODE_ENV", "value": "production" }] }, "message": "OK", "requestId": "…" }Set environment variables
/api/v1/applications/:id/environmentReplaces the whole list. The new values go live on the next deploy or when you apply. 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 -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"}]}'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
/api/v1/applications/:id/deployDeploys 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 -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/deploy \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/applications/:id/rollbackMakes 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 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"}'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
/api/v1/applications/:id/:actionaction is start, stop or restart. Works on a deployed app.
Example request
curl -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/restart \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/applications/:id/applyWrites 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.
Scale
/api/v1/applications/:id/scaleSets 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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
instances | integer | Yes | 1 to 16. |
Example request
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}'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.
Refresh process state
/api/v1/applications/:id/statusQueues 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
/api/v1/applications/:id/logsQueues 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 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}'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
/api/v1/applications/:id/websiteGives an app without a website one: a reverse proxy from the domains to the app's port. Then issue a 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
/api/v1/applications/:id/webhookCreates (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.
Example request
curl -X POST https://panel.example.com/api/v1/applications/5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c/webhook \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"Response 200 OK
{
"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
/api/v1/applications/:id/webhookResponse 200 OK with { application }, message Push to deploy turned off.
List deployments
/api/v1/deploymentsApp deployments and rollbacks across all apps, newest first. Supports the list parameters.
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 "https://panel.example.com/api/v1/deployments?applicationId=5c4b3a29-8d7e-4f6a-b5c4-3d2e1f0a9b8c" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.deployments.list({ applicationId: appId });Response 200 OK: { items: [deployment], pagination }.
Get a deployment
/api/v1/deployments/:idExample request
curl https://panel.example.com/api/v1/deployments/9e8d7c6b-5a49-4382-9170-8f7e6d5c4b3a \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const deployment = await panel.deployments.get(deploymentId);Response 200 OK
{
"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.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such deployment. |
Git push hook
/api/v1/hooks/deploy/:tokenThe URL Git hosts call on a push, for both apps and Git-deployed websites. 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
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
{ "success": true, "data": { "ignored": false, "deploymentId": "9e8d7c6b-…", "releaseId": "20261110113000-a1b2c3" }, "message": "Deploying", "requestId": "…" }Response 200 OK, ignored
{ "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.
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
/api/v1/cms/appsThe catalog above, with each app's description and where it is downloaded from. Any signed-in caller may read it.
Example request
curl https://panel.example.com/api/v1/cms/apps \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { apps } = await panel.cms.catalog();Response 200 OK
{
"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
/api/v1/cms/installsQuery 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 "https://panel.example.com/api/v1/cms/installs?websiteId=0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.cms.installs({ websiteId });Response 200 OK
{
"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
/api/v1/cms/installsInstalls 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 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"}'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
{
"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
/api/v1/cms/installs/:idResponse 200 OK with the installed app, as in List installed apps. 404 NOT_FOUND when there is no such install.
Remove an installed app
/api/v1/cms/installs/:idRemoves 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 -X DELETE "https://panel.example.com/api/v1/cms/installs/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d?removeDatabase=true" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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. |