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.

Last updated

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

MethodPathDescription
GET/api/v1/applicationsList applications
GET/api/v1/applications/suggest-portSuggest a port
POST/api/v1/applicationsCreate an application
GET/api/v1/applications/:idGet an application
PATCH/api/v1/applications/:idUpdate an application
DELETE/api/v1/applications/:idDelete an application
GET/api/v1/applications/:id/environmentGet environment variables
PUT/api/v1/applications/:id/environmentSet environment variables
POST/api/v1/applications/:id/deployDeploy
POST/api/v1/applications/:id/rollbackRoll back
POST/api/v1/applications/:id/startStart, stop or restart
POST/api/v1/applications/:id/stopStart, stop or restart
POST/api/v1/applications/:id/restartStart, stop or restart
POST/api/v1/applications/:id/applyApply settings
POST/api/v1/applications/:id/scaleScale
POST/api/v1/applications/:id/statusRefresh process state
POST/api/v1/applications/:id/logsRead application logs
POST/api/v1/applications/:id/websiteAdd a website
POST/api/v1/applications/:id/webhookTurn push to deploy on
DELETE/api/v1/applications/:id/webhookTurn push to deploy off
GET/api/v1/deploymentsList deployments
GET/api/v1/deployments/:idGet a deployment
POST/api/v1/hooks/deploy/:tokenGit push hook
GET/api/v1/cms/appsList installable apps
GET/api/v1/cms/installsList installed apps
POST/api/v1/cms/installsInstall an app
GET/api/v1/cms/installs/:idGet an installed app
DELETE/api/v1/cms/installs/:idRemove an installed app

Runtimes

runtimeDefault start commandNotes
nodenpm startRuns with the server's system-wide Node.js; dependencies installed with npm. Can run several copies and reload without downtime.
pythongunicorn app:appRuns in its own virtual environment; dependencies from requirements.txt.
go./appBuilt with the server's Go (default build command go build -o app .). One process. Agent 0.32.0.
rubybundle exec puma -b tcp://127.0.0.1:$PORTGems 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"
}
FieldDescription
statuscreating, ready, deploying, updating, deleting or failed.
currentThe live release, or null before the first deploy.
processThe last process state the agent reported (PM2), or null.
deployKeyThe public key to add to the repository as a read-only deploy key, for private repositories over SSH.
cpuLimitPercent, memoryLimitMbResource caps, or null for none. CPU is a percentage of one core (10 to 6400); memory is in MiB (64 to 262144).
instancesCopies of the app that run, 1 to 16.
website, envKeysFilled by Get an application: the linked website and the names (not values) of the environment variables.

List applications

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

Apps, newest first. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches name, repository URL or domain.
serverIdstringNoApps on one server.
statusstringNoOne of the statuses above.
runtimestringNonode, python, go or ruby.
sortstringNocreatedAt (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

GET/api/v1/applications/suggest-port
Auth
Session cookie (+ CSRF token) or API token
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

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

POST/api/v1/applications
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
serverIdstringYesThe server to run it on.
namestringYes3 to 32 lowercase letters, digits and dashes, starting with a letter. The Linux user and folder; unique per server among apps and websites.
runtimestringYesnode, python, go or ruby.
repositoryUrlstringYesAn https:// or SSH Git URL, without a password in it.
branchstringNoDefault main.
installCommandstringNoUp to 10 lines of up to 500 characters.
buildCommandstringNoSame limits.
startCommandstringNoOne line. Defaults to the runtime's start command.
portinteger or nullWith domains1024 to 65535; not 3306, 5432, 6379, 11211 or 27017. A hosting customer must use one of their own ports.
keepReleasesintegerNoReleases kept for rollbacks, 1 to 20. Default 5.
healthCheckSecondsintegerNoHow long a new release must stay up, 5 to 300. Default 30.
domainsstring[]NoUp to 20 domains for the linked website.
envobject[]NoUp to 100 { key, value }. PORT, PATH, HOME, USER and PM2_HOME are set by VaultPanel.
deployNowbooleanNoDeploy 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

StatusCodeWhen
403FORBIDDENdomains without websites.manage.
409SERVER_NOT_READYThe server has no connected agent yet.
409SOFTWARE_MISSINGGit, PM2 or the runtime is not installed (details.missing).
409NODE_IN_HOME_FOLDERNode.js is installed in a home folder (for example by nvm). Install it system-wide.
409AGENT_OUTDATEDThe agent is too old to run apps, or to run Go or Ruby apps.
409NGINX_NOT_INSTALLEDdomains given and NGINX is not installed.
409QUOTA_REACHEDA hosting customer's plan allows no more apps.
422VALIDATION_ERRORA field is invalid, the name or port is taken, or domains without port.

Get an application

GET/api/v1/applications/:id
Auth
Session cookie (+ CSRF token) or API token
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 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

PATCH/api/v1/applications/:id
Auth
Session cookie (+ CSRF token) or API token
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. Send at least one field. A hosting customer's CPU and memory limits are capped by their plan.

Request body

FieldTypeRequiredDescription
repositoryUrl, branchstringNoAs for create.
installCommand, buildCommandstring or nullNoAs for create; null removes it.
startCommandstringNoOne line. Cannot be empty.
portinteger or nullNonull runs the app without a port, unless it has a website.
keepReleases, healthCheckSecondsintegerNoAs for create.
cpuLimitPercentinteger or nullNo10 to 6400 (percent of one core), or null for none.
memoryLimitMbinteger or nullNo64 to 262144, or null for none.
instancesintegerNo1 to 16 copies. More than one needs agent 0.14.0 and a Node.js or Python app.
zeroDowntimebooleanNoNode.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

StatusCodeWhen
409APPLICATION_BUSYAnother change is running.
409AGENT_OUTDATEDSeveral copies or zero-downtime reloads need a newer agent.
422VALIDATION_ERRORAn 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
Auth
Session cookie (+ CSRF token) or API token
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

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

StatusCodeWhen
403FORBIDDENThe app has a website and you lack websites.manage.
409APPLICATION_BUSYAnother change is running.

Get environment variables

GET/api/v1/applications/:id/environment
Auth
Session cookie (+ CSRF token) or API token
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 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

PUT/api/v1/applications/:id/environment
Auth
Session cookie (+ CSRF token) or API token
Permission
applications.manage
Token scope
manage

Replaces 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

FieldTypeRequiredDescription
variablesobject[]YesUp 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

StatusCodeWhen
409APPLICATION_BUSYAnother change is running.
422VALIDATION_ERRORAn invalid, reserved or repeated key, or a value too long (details names variables.N.key…).

Deploy

POST/api/v1/applications/:id/deploy
Auth
Session cookie (+ CSRF token) or API token
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 -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

StatusCodeWhen
409APPLICATION_BUSYAnother change is running.
409APPLICATION_NOT_READYThe app is still being set up.
409SERVER_NOT_READY, SOFTWARE_MISSING, AGENT_OUTDATED, NODE_IN_HOME_FOLDERAs for create.

Roll back

POST/api/v1/applications/:id/rollback
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
deploymentIdstringYesA 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

StatusCodeWhen
404NOT_FOUNDNo such deployment of this app.
409APPLICATION_NOT_DEPLOYEDThe app has never been deployed.
409RELEASE_ALREADY_LIVEThat release is already live.
409RELEASE_NOT_DEPLOYABLEThat deployment did not succeed.
409RELEASE_NOT_FOUNDIts release was removed from the server. Deploy its commit again instead.

Start, stop or restart

POST/api/v1/applications/:id/:action
Auth
Session cookie (+ CSRF token) or API token
Permission
applications.deploy
Token scope
deploy

action 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

StatusCodeWhen
409APPLICATION_NOT_DEPLOYEDDeploy the app first.
409APPLICATION_BUSY, APPLICATION_NOT_READYSee above.

Apply settings

POST/api/v1/applications/:id/apply
Auth
Session cookie (+ CSRF token) or API token
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.

Scale

POST/api/v1/applications/:id/scale
Auth
Session cookie (+ CSRF token) or API token
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.

Request body

FieldTypeRequiredDescription
instancesintegerYes1 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

POST/api/v1/applications/:id/status
Auth
Session cookie (+ CSRF token) or API token
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

StatusCodeWhen
409APPLICATION_NOT_READYThe app is not set up on its server yet.

Read application logs

POST/api/v1/applications/:id/logs
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
logstringYesoutput or error.
linesintegerNo10 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

POST/api/v1/applications/:id/website
Auth
Session cookie (+ CSRF token) or API token
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 on the new website.

Request body

FieldTypeRequiredDescription
domainsstring[]Yes1 to 20 domains.

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

Errors

StatusCodeWhen
409APPLICATION_HAS_WEBSITEThe app already has a website. Add domains to that website instead.
422VALIDATION_ERRORThe app has no port, or a domain is invalid or taken.

Turn push to deploy on

POST/api/v1/applications/:id/webhook
Auth
Session cookie (+ CSRF token) or API token
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.

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

DELETE/api/v1/applications/:id/webhook
Auth
Session cookie (+ CSRF token) or API token
Permission
applications.manage
Token scope
manage

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

List deployments

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

App deployments and rollbacks across all apps, newest first. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
applicationIdstringNoDeployments of one app.
serverIdstringNoDeployments on one server.
statusstringNorunning, 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

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

Example 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

StatusCodeWhen
404NOT_FOUNDNo such deployment.

Git push hook

POST/api/v1/hooks/deploy/:token
Auth
Token in the URL

The 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 hostSignature
GitHub, Gitea, Forgejo, BitbucketHMAC-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>).
GitLabThe 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

StatusCodeWhen
401WEBHOOK_SIGNATURE_INVALIDThe signature is missing or does not match. The rejection is audited.
404NOT_FOUNDUnknown webhook token.
409APPLICATION_BUSY, WEBSITE_BUSYA change is already running.
429RATE_LIMITEDMore 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.

appInstalls intoMinimum PHPAdmin page
wordpressA folder of the document root, or the root7.4wp-admin/
joomlaA folder of the document root, or the root8.1administrator/
drupalA project folder (default drupal); the site serves its web folder8.1user/login
laravelA project folder (default laravel); the site serves its public folder8.2None

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
Auth
Session cookie (+ CSRF token) or API token

The 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

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

Query parameters

NameTypeRequiredDescription
websiteIdstringNoApps in one website.
serverIdstringNoApps on one server.
page, pageSizeintegerNoPaging.

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

POST/api/v1/cms/installs
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
appstringYeswordpress, joomla, drupal or laravel.
websiteIdstringOne of the twoAn existing PHP website.
newWebsiteobjectOne of the two{ serverId, name, domains, phpVersion } for a new PHP website.
pathstringNoA 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.
titlestringNoThe site title, up to 100 characters.
adminUserstringNo3 to 60 letters, digits, dots, dashes and underscores.
adminEmailstringNoThe admin's email address.
adminPasswordstringNo12 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

StatusCodeWhen
403FORBIDDENYou lack websites.manage or databases.manage.
409WEBSITE_NOT_READYThe website is not ready yet.
409PANEL_WEBSITEThe website serves VaultPanel itself.
409WEBSITE_OWNED_BY_APPThe website serves an app.
409CMS_PHP_TOO_OLDThe website's PHP version is older than the app needs.
409CMS_SITE_TAKENA Drupal or Laravel app already uses the document root, or Drupal or Laravel would take over a website that already has an app.
409AGENT_OUTDATEDThe agent is older than 0.20.0.
409QUOTA_REACHEDA hosting customer's plan allows no more websites, databases or database users.
422VALIDATION_ERRORNot exactly one of websiteId and newWebsite, or an invalid field.

Get an installed app

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

Response 200 OK with the installed app, as in List installed apps. 404 NOT_FOUND when there is no such install.

Remove an installed app

DELETE/api/v1/cms/installs/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.manage
Token scope
manage

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

Query parameters

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

StatusCodeWhen
409CMS_BUSYThe app is still being installed, or already being removed.