API Reference

Websites

API reference for websites, SSL certificates, website files, uptime checks, Git deploy for static and PHP sites, subdomains and domains.

Last updated

A website is a site NGINX serves on one of your servers: static files, a PHP site on its own PHP-FPM pool, or a reverse proxy to an app's port. The site's name is also its Linux user and the folder under /var/www. See Websites.

Hosting customers can use every endpoint on this page for their own websites, except custom NGINX rules, which are set by their host.

How changes work

Creating, changing, enabling, disabling and deleting a website, and every SSL change, returns 202 Accepted with { website, job }. The panel saves the request, the agent carries it out, and the website keeps its current settings until the job succeeds. While it runs, status is creating, updating or deleting and pendingAction names the change. A failed change leaves the settings as they were and sets lastError. A request that changes nothing answers 200 with job: null.

Only one change runs at a time: another change while one is running answers 409 WEBSITE_BUSY with the running job's id in details.jobId.

File and log requests are jobs too. Their result arrives in the job's output; poll GET /jobs/:id for it.

Endpoints

MethodPathDescription
GET/api/v1/websitesList websites
POST/api/v1/websitesCreate a website
GET/api/v1/websites/:idGet a website
PATCH/api/v1/websites/:idUpdate a website
DELETE/api/v1/websites/:idDelete a website
POST/api/v1/websites/:id/enableEnable or disable a website
POST/api/v1/websites/:id/disableEnable or disable a website
POST/api/v1/websites/:id/retryRetry creating a website
POST/api/v1/websites/:id/sslIssue a Let's Encrypt certificate
POST/api/v1/websites/:id/ssl/uploadInstall your own certificate
POST/api/v1/websites/:id/ssl/renewRenew a certificate
DELETE/api/v1/websites/:id/sslTurn HTTPS off
POST/api/v1/websites/:id/logsRead website logs
POST/api/v1/websites/:id/dns-checkCheck a website's DNS
GET/api/v1/websites/:id/uptimeGet uptime
PUT/api/v1/websites/:id/uptimeTurn uptime monitoring on or off
POST/api/v1/websites/:id/uptime/checkCheck uptime now
POST/api/v1/websites/:id/files/:actionRun a file action
POST/api/v1/websites/:id/files/uploadsUpload a large file
PUT/api/v1/websites/:id/files/uploads/:uploadId/chunks/:offsetUpload a large file
POST/api/v1/websites/:id/files/uploads/:uploadId/finishUpload a large file
POST/api/v1/websites/:id/files/downloadsDownload a file
GET/api/v1/websites/:id/files/downloads/:downloadIdDownload a file
GET/api/v1/websites/:id/files/downloads/:downloadId/fileDownload a file
PUT/api/v1/websites/:id/gitSet up Git deploy
DELETE/api/v1/websites/:id/gitTurn Git deploy off
POST/api/v1/websites/:id/deployDeploy a website from Git
POST/api/v1/websites/:id/rollbackRoll back a website
GET/api/v1/websites/:id/deploymentsList website deployments
GET/api/v1/websites/:id/environmentGet or set build variables
PUT/api/v1/websites/:id/environmentGet or set build variables
POST/api/v1/websites/:id/git/webhookTurn push to deploy on or off
DELETE/api/v1/websites/:id/git/webhookTurn push to deploy on or off
GET/api/v1/subdomains/parentsList subdomain parents
POST/api/v1/subdomainsCreate a subdomain
GET/api/v1/domainsList domains
POST/api/v1/domains/:id/dns-checkCheck a domain's DNS
GET/api/v1/ssl-certificatesList certificates
GET/api/v1/ssl-certificates/renewalGet renewal settings
PUT/api/v1/ssl-certificates/renewalChange renewal settings

The website object

{
  "id": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
  "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
  "serverName": "web-1",
  "serverStatus": "online",
  "customerId": null,
  "subdomainOf": null,
  "dnsRecords": [],
  "name": "shop",
  "type": "php",
  "primaryDomain": "shop.example.com",
  "domains": [
    {
      "id": "d4c3b2a1-…",
      "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
      "domain": "shop.example.com",
      "isPrimary": true,
      "dns": { "status": "ok", "addresses": ["203.0.113.10"], "checkedAt": "2026-11-10T09:00:00.000Z" },
      "createdAt": "2026-11-01T10:00:00.000Z"
    }
  ],
  "documentRoot": "public",
  "phpVersion": "8.3",
  "proxyPort": null,
  "customNginx": "",
  "htaccess": false,
  "spa": false,
  "isEnabled": true,
  "forceHttps": true,
  "status": "active",
  "pendingAction": null,
  "provisioned": true,
  "health": { "status": "ok", "message": "HTTP 200", "checkedAt": "2026-11-01T10:00:20.000Z" },
  "uptime": { "enabled": true, "status": "up", "since": "2026-11-01T10:05:00.000Z", "checkedAt": "2026-11-10T11:00:00.000Z", "message": null },
  "ssl": {
    "id": "6a5b4c3d-…",
    "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
    "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
    "certName": "vp-shop",
    "provider": "letsencrypt",
    "dnsProviderId": null,
    "status": "active",
    "state": "active",
    "daysLeft": 81,
    "domains": ["shop.example.com"],
    "issuer": "R11",
    "isStaging": false,
    "email": "ada@example.com",
    "notBefore": "2026-11-01T09:00:00.000Z",
    "notAfter": "2027-01-30T09:00:00.000Z",
    "issuedAt": "2026-11-01T10:02:00.000Z",
    "lastJobId": "…",
    "lastError": null,
    "updatedAt": "2026-11-01T10:02:00.000Z"
  },
  "application": null,
  "git": null,
  "uncoveredDomains": [],
  "lastJobId": "…",
  "lastError": null,
  "createdAt": "2026-11-01T10:00:00.000Z",
  "updatedAt": "2026-11-01T10:02:00.000Z"
}
FieldDescription
typestatic, php or proxy.
statuscreating, active, updating, disabled, deleting or failed.
domainsThe first is the primary domain. dns.status is ok (points at the server), mismatch, unresolved or error, after a DNS check.
documentRootThe folder inside the site that is served, such as public.
customNginx, htaccess, spaCustom NGINX rules, .htaccess support through Apache, and the single-page app setting (static sites). See NGINX rules and .htaccess.
healthThe agent's check right after the last change: status is ok or failing.
uptimeThe panel's own uptime checks. Get uptime has more.
sslThe certificate, or null. status is pending, active, failed or inactive; state adds expiring and expired. provider is letsencrypt or custom (uploaded).
applicationThe app this site serves as a reverse proxy, or null.
gitGit deploy settings, or null while the site is managed with the file manager. See Set up Git deploy.
uncoveredDomainsDomains added after the active certificate was issued, which it does not cover.
subdomainOf, dnsRecordsFor sites added as subdomains: the parent domain and the DNS records the panel added.

List websites

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

Websites, newest first. Hosting customers see only their own. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches the site name or any of its domains.
serverIdstringNoSites on one server.
statusstringNoOne of the statuses above.
subdomainsbooleanNotrue lists only sites added as subdomains.
sortstringNocreatedAt (default) or name.

Example request

curl "https://panel.example.com/api/v1/websites?search=example.com" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.websites.list({ search: 'example.com' });

Response 200 OK: { items: [website], pagination }.

Create a website

POST/api/v1/websites
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.manage
Token scope
manage

Saves the website and queues a CREATE_SITE job that creates its Linux user and folders, its PHP-FPM pool for PHP sites, and its NGINX configuration, then checks it answers. NGINX must be installed on the server.

Request body

FieldTypeRequiredDescription
serverIdstringYesThe server to create it on.
namestringYes3 to 32 lowercase letters, digits and dashes, starting with a letter. Becomes the Linux user and folder name; unique per server among websites and apps.
typestringYesstatic, php or proxy.
domainsstring[]Yes1 to 20 domains; the first is the primary one. A domain may be a wildcard one level deep, such as *.example.com (agent 0.37.0 or later).
documentRootstringNoThe folder inside the site to serve. Default public.
phpVersionstringFor phpA PHP version installed on the server, such as 8.3.
proxyPortintegerFor proxyThe local port of the app to forward to, 1 to 65535. A hosting customer may only point at one of their own apps.

A wildcard domain serves every name under its domain that no other site lists itself, since NGINX prefers exact names. It cannot sit directly on a registry suffix such as *.co.uk.

Example request

curl https://panel.example.com/api/v1/websites \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
    "name": "shop",
    "type": "php",
    "domains": ["shop.example.com", "www.shop.example.com"],
    "phpVersion": "8.3"
  }'
const { website, job } = await panel.websites.create({
  serverId,
  name: 'shop',
  type: 'php',
  domains: ['shop.example.com', 'www.shop.example.com'],
  phpVersion: '8.3',
});
await panel.jobs.wait(job.id);

Response 202 Accepted

{
  "success": true,
  "data": {
    "website": { "id": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a", "name": "shop", "type": "php", "status": "creating", "pendingAction": "create", "provisioned": false },
    "job": { "id": "a1d3c5e7-…", "type": "CREATE_SITE", "status": "queued" }
  },
  "message": "Website saved. The agent is creating it on the server.",
  "requestId": "…"
}

Errors

StatusCodeWhen
409SERVER_NOT_READYThe server has no connected agent yet.
409NGINX_NOT_INSTALLEDInstall the web stack on the server first.
409AGENT_OUTDATEDA wildcard domain needs agent 0.37.0 or later.
409QUOTA_REACHEDA hosting customer's plan allows no more websites.
422VALIDATION_ERRORAn invalid field, a name or domain already taken, a missing phpVersion or proxyPort, or a server that was not found.

Get a website

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

The website with its 10 most recent change jobs in recentJobs (creation, configuration, SSL, file changes and Git deploys).

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const website = await panel.websites.get(websiteId);

Response 200 OK: the website object with recentJobs.

Errors

StatusCodeWhen
404NOT_FOUNDNo such website, or not yours.

Update a website

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

Changes a website's settings. The changes are merged with the current ones, checked again and applied by a CREATE_NGINX_CONFIG job. Send at least one field.

Request body

FieldTypeRequiredDescription
typestringNostatic, php or proxy.
domainsstring[]NoThe full new list, 1 to 20; the first is primary.
documentRootstringNoThe folder to serve.
phpVersionstring or nullNoFor PHP sites.
proxyPortinteger or nullNoFor reverse proxies.
forceHttpsbooleanNoRedirect HTTP to HTTPS. Needs an active certificate.
customNginxstringNoCustom NGINX rules for the site's server block, up to 8192 characters. Staff only; needs agent 0.18.0.
htaccessbooleanNoHonour .htaccess files through Apache behind NGINX. Needs agent 0.18.0.
spabooleanNoStatic sites: serve index.html for every path a file does not match. Needs agent 0.30.0.

Example request

curl -X PATCH https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"phpVersion":"8.4","forceHttps":true}'
const { website, job } = await panel.websites.update(websiteId, { phpVersion: '8.4', forceHttps: true });

Response 202 Accepted with { website, job }, or 200 OK with job: null when nothing changes.

Errors

StatusCodeWhen
403FORBIDDENA hosting customer sent customNginx.
409WEBSITE_BUSYAnother change is running (details.jobId).
409WEBSITE_NOT_READYThe site was never created on its server. Retry or delete it.
409WEBSITE_OWNED_BY_APPThe site serves an app; change the app's port instead.
409WEBSITE_GIT_DEPLOYThe site deploys from Git; turn Git deploy off before changing its type.
409PANEL_WEBSITEThe site serves the panel's own domain. Change it on the Panel Domain page.
409AGENT_OUTDATEDThe setting needs a newer agent.
422VALIDATION_ERRORAn invalid value, forceHttps without a certificate, or nothing to update.

Delete a website

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

Removes the site from NGINX (and its PHP-FPM pool) with a DELETE_SITE job. Its files stay unless you ask for them to be removed.

Query parameters

NameTypeRequiredDescription
removeFilesbooleanNoAlso delete the site's folder and Linux user. Default false.

Example request

curl -X DELETE "https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a?removeFiles=true" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { job } = await panel.websites.remove(websiteId, { removeFiles: true });

Response 202 Accepted with { website, job } (status: "deleting").

Errors

StatusCodeWhen
409WEBSITE_BUSYAnother change is running.
409WEBSITE_OWNED_BY_APPremoveFiles=true on a site that serves an app: the files belong to the app.
409PANEL_WEBSITEThe site serves the panel's own domain.

Enable or disable a website

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

A disabled website keeps its settings and files but NGINX stops serving it.

Example request

curl -X POST https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/disable \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.websites.disable(websiteId);
await panel.websites.enable(websiteId);

Response 202 Accepted with { website, job }, or 200 OK with job: null when it is already in that state. Errors as for Update a website.

Retry creating a website

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

Queues CREATE_SITE again for a website whose creation failed.

Response 202 Accepted with { website, job }.

Errors

StatusCodeWhen
409WEBSITE_READYThe website already exists on its server.
409WEBSITE_BUSYAnother change is running.

Issue a Let's Encrypt certificate

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

Requests a free certificate from Let's Encrypt with Certbot (ISSUE_SSL) for the site's domains and turns HTTPS on. Let's Encrypt must reach the site over HTTP, so the site must be enabled and its domains must point at the server. Renewal is automatic. See SSL certificates.

Wildcard certificates. With wildcard: true, one certificate covers the domain and *.domain, checked through DNS: the domain needs an active DNS zone on the site's server. Or pass dnsProviderId to check it through Cloudflare or Namecheap instead, with no zone on the server (staff with dns.read, agent 0.38.0 or later). Without either, the site's wildcard domains are left out of the certificate; a site whose domains are all wildcards always asks for a wildcard certificate.

Request body

FieldTypeRequiredDescription
emailstringYesLet's Encrypt's contact address for expiry notices.
stagingbooleanNoUse Let's Encrypt's staging service, for a test certificate browsers do not trust. Default false.
verifyDnsbooleanNoCheck the domains point at the server first. Default true.
forceHttpsbooleanNoRedirect HTTP to HTTPS once issued. Default true.
wildcardbooleanNoAsk for a wildcard certificate through the server's DNS zone. Default false.
dnsProviderIdstring or nullNoA DNS provider to check a wildcard certificate through.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/ssl \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","forceHttps":true}'
const { job } = await panel.websites.issueSsl(websiteId, { email: 'ada@example.com', forceHttps: true });
await panel.jobs.wait(job.id);

Response 202 Accepted with { website, job }. The certificate is pending until the job finishes.

Errors

StatusCodeWhen
403FORBIDDENdnsProviderId from a hosting customer, or without dns.read.
409SITE_DISABLEDEnable the website first.
409CERTBOT_NOT_INSTALLEDInstall Certbot from the server's web stack first.
409DNS_ZONE_MISSINGA wildcard certificate needs a DNS zone for the domain on this server.
409AGENT_OUTDATEDWildcard certificates need agent 0.28.0, DNS providers 0.38.0.
409DNS_PROVIDER_NO_ADDRESSNamecheap needs the server's public IPv4 address, which the panel does not know.
409WEBSITE_BUSY, WEBSITE_NOT_READYSee Update a website.
422WILDCARD_NOT_POSSIBLEThe site's domains do not fit one wildcard certificate.
422DNS_PROVIDER_DOMAINThe panel cannot tell which Namecheap domain the name belongs to.

Install your own certificate

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

Installs a certificate bought elsewhere (INSTALL_SSL_CERT). The agent checks that the key matches, the certificate is valid now and it covers every domain of the site before it goes live. The private key is removed from the stored job. Uploaded certificates show provider: "custom" and are never renewed by the panel. Needs agent 0.28.0.

Request body

FieldTypeRequiredDescription
certificatestringYesPEM certificate with its chain, up to 65536 characters.
privateKeystringYesPEM private key, up to 16384 characters.
forceHttpsbooleanNoRedirect HTTP to HTTPS. Default true.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/ssl/upload \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile cert fullchain.pem --rawfile key privkey.pem '{certificate: $cert, privateKey: $key}')"

Response 202 Accepted with { website, job }.

Errors

StatusCodeWhen
409AGENT_OUTDATEDThe agent is older than 0.28.0.
409WEBSITE_BUSY, WEBSITE_NOT_READYSee Update a website.
422VALIDATION_ERRORThe PEM data is missing or not a certificate and key.

Renew a certificate

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

Renews a Let's Encrypt certificate now (RENEW_SSL). Without force, Certbot renews only inside the renewal window. Certificates also renew on their own; see Get renewal settings.

Request body

FieldTypeRequiredDescription
forcebooleanNoRenew even when the certificate is not due. Default false.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/ssl/renew \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" -d '{"force":true}'
await panel.websites.renewSsl(websiteId, { force: true });

Response 202 Accepted with { website, job }.

Errors

StatusCodeWhen
409SSL_NOT_FOUNDThe site has no certificate yet.
409SSL_CUSTOMThe certificate was uploaded; upload the renewed one instead.
409WEBSITE_BUSYAnother change is running.

Turn HTTPS off

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

Serves the site over HTTP only again. The certificate stays on the server until the site is deleted, so HTTPS can be turned back on.

Example request

curl -X DELETE https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/ssl \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.websites.disableSsl(websiteId);

Response 202 Accepted with { website, job }.

Errors

StatusCodeWhen
409SSL_NOT_ACTIVEHTTPS is not on for this website.

Read website logs

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

Queues a routine SITE_LOGS job that reads the last lines of the site's NGINX access or error log. The lines arrive in the job's output.

Request body

FieldTypeRequiredDescription
logstringYesaccess or error.
linesintegerNo10 to 2000. Default 200.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/logs \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"log":"error","lines":100}'
const job = await panel.websites.logs(websiteId, { log: 'error', lines: 100 });
const { job: done } = await panel.jobs.wait(job.id);
console.log(done.output);

Response 202 Accepted with the job.

Errors

StatusCodeWhen
409WEBSITE_NOT_READYThe site does not exist on its server yet.

Check a website's DNS

POST/api/v1/websites/:id/dns-check
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.read
Token scope
read

Looks up every domain of the site in public DNS and compares the addresses with the server's. The result is saved on each domain. For a wildcard domain, a random name under it is looked up.

Example request

curl -X POST https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/dns-check \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.websites.checkDns(websiteId);

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "d4c3b2a1-…",
        "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
        "domain": "shop.example.com",
        "isPrimary": true,
        "dns": { "status": "ok", "addresses": ["203.0.113.10"], "checkedAt": "2026-11-10T11:30:00.000Z" },
        "createdAt": "2026-11-01T10:00:00.000Z",
        "serverAddresses": ["203.0.113.10"],
        "detail": null
      }
    ]
  },
  "message": "DNS checked",
  "requestId": "…"
}

dns.status is ok (an address matches the server), mismatch (it resolves elsewhere), unresolved (no A or AAAA records) or error (the lookup failed; detail says why).

Get uptime

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

The panel checks each enabled website the way visitors reach it, every VAULTPANEL_UPTIME_CHECK_SECONDS (300 by default): the primary domain, or the first that is not a wildcard, over HTTPS when the certificate covers it. A site is down after no answer, an HTTP 5xx or a certificate browsers refuse, twice in a row 10 seconds apart. See Uptime monitoring.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/uptime \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"

Response 200 OK

{
  "success": true,
  "data": {
    "uptime": {
      "enabled": true,
      "intervalSeconds": 300,
      "status": "up",
      "since": "2026-11-01T10:05:00.000Z",
      "checkedAt": "2026-11-10T11:30:00.000Z",
      "message": null,
      "responseMs": 84,
      "url": "https://shop.example.com/",
      "certificateValidTo": "2027-01-30T09:00:00.000Z",
      "day": 100,
      "week": 99.9,
      "month": 99.97,
      "averageMs": 91,
      "incidents": [
        { "id": "…", "startedAt": "2026-11-06T02:10:00.000Z", "endedAt": "2026-11-06T02:25:00.000Z", "message": "HTTP 502" }
      ]
    }
  },
  "message": "OK",
  "requestId": "…"
}

status is up, down or null (not checked yet). day, week and month are uptime percentages; averageMs is the last day's average response time; incidents are the 10 most recent downtimes.

Turn uptime monitoring on or off

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

Turning monitoring off forgets the current status and ends any open downtime, so its Website down alert resolves.

Request body

FieldTypeRequiredDescription
enabledbooleanYesCheck this website.

Example request

curl -X PUT https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/uptime \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" -d '{"enabled":false}'

Response 200 OK, the same as Get uptime.

Check uptime now

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

Checks the website once, now, without the second try.

Response 200 OK, the same as Get uptime, message Checked.

Errors

StatusCodeWhen
409UPTIME_NOT_CHECKEDMonitoring is off for this website, or the website is disabled.

Run a file action

POST/api/v1/websites/:id/files/:action
Auth
Session cookie (+ CSRF token) or API token
Permission
files.read, files.write
Token scope
manage

The file manager. Each action queues a job that the agent runs as the site's own user, inside the site's home folder. list and read need files.read and are routine jobs; the others need files.write. The result is in the job's output.

Paths are relative to the site's home folder. Absolute paths, .. and control characters are refused. Files up to 1 MB can be read or written this way; use Upload a large file and Download a file for bigger ones. Written contents never reach the audit log and are removed from the stored job, and read results are deleted an hour after the job.

ActionBodyWhat it does
listpath (default "", the home folder)Lists a folder.
readpathReads a file up to 1 MB.
writepath, content, encoding (utf8 or base64, default utf8), overwrite (default true)Saves a file up to 1 MB.
mkdirpathCreates a folder.
renamefrom, toRenames or moves a file or folder.
deletepathDeletes a file or folder.
extractpath (a .zip, .tar.gz, .tgz or .tar), to (default ""), overwrite (default false)Unpacks an archive; to is created when missing.
compressfolder (default ""), names (1 to 200 names in the folder), to (a path ending in .zip)Makes a zip.
chmodpath, mode (three octal digits such as 755), recursive (default false), fileMode (required with recursive)Changes permissions. With recursive, folders inside get mode and files fileMode; links are skipped.

Example request

curl https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/files/list \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"path":"public"}'
const job = await panel.websites.files(websiteId, 'list', { path: 'public' });
const { job: done } = await panel.jobs.wait(job.id, { intervalMs: 500 });
for (const entry of done.output.entries) console.log(entry.type, entry.name);

Response 202 Accepted with the job, message Queued. A finished list job's output looks like:

{
  "path": "public",
  "entries": [
    { "name": "assets", "type": "dir", "size": null, "mode": "0755", "modifiedAt": "2026-11-09T14:02:11.000Z" },
    { "name": "index.php", "type": "file", "size": 1830, "mode": "0644", "modifiedAt": "2026-11-09T14:02:11.000Z" }
  ],
  "total": 2,
  "truncated": false
}

type is dir, file, link or other.

Errors

StatusCodeWhen
409WEBSITE_NOT_READYThe site's files are not available (being created or deleted).
422VALIDATION_ERRORUnknown action, or an invalid path or field.

Upload a large file

Files larger than 1 MB, up to VAULTPANEL_FILE_UPLOAD_MAX_MB (2048 by default), go up in three steps, all with files.write:

POST/api/v1/websites/:id/files/uploads
Auth
Session cookie (+ CSRF token) or API token
Permission
files.write
Token scope
manage
PUT/api/v1/websites/:id/files/uploads/:uploadId/chunks/:offset
Auth
Session cookie (+ CSRF token) or API token
Permission
files.write
Token scope
manage
POST/api/v1/websites/:id/files/uploads/:uploadId/finish
Auth
Session cookie (+ CSRF token) or API token
Permission
files.write
Token scope
manage
  1. Start with { path, size, overwrite } (overwrite defaults to false). The panel answers 201 Created with { uploadId, chunkBytes, size }.
  2. Send the pieces in order as raw bytes (Content-Type: application/octet-stream), each up to chunkBytes (8 MB), at the byte offset it starts at. Each answers { received, size }.
  3. Finish. The panel answers 202 Accepted with a FILE_UPLOAD job: the agent fetches the file from the panel, checks its SHA-256 and saves it as the site's user.

Only the person who started an upload can continue it.

SITE=0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a
API=https://panel.example.com/api/v1/websites/$SITE/files/uploads
SIZE=$(stat -c %s backup.zip)

UPLOAD=$(curl -s "$API" -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d "{\"path\":\"backup.zip\",\"size\":$SIZE}" | jq -r .data.uploadId)

split -b 8M -d backup.zip part-
OFFSET=0
for PART in part-*; do
  curl -s -X PUT "$API/$UPLOAD/chunks/$OFFSET" -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
    -H "Content-Type: application/octet-stream" --data-binary @"$PART" > /dev/null
  OFFSET=$((OFFSET + $(stat -c %s "$PART")))
done

curl -s -X POST "$API/$UPLOAD/finish" -H "Authorization: Bearer $VAULTPANEL_TOKEN"

Errors

StatusCodeWhen
400BAD_REQUESTA piece arrived without a body.
404NOT_FOUNDNo such upload, or it is not yours.
409OFFSET_MISMATCHThe piece does not start where the last one ended (details.expected).
409UPLOAD_INCOMPLETEFinished before every byte arrived (details.received).
409UPLOAD_FINISHEDThe upload is already complete.
413FILE_TOO_LARGEsize is over the panel's upload limit.
413CHUNK_TOO_LARGEA piece is larger than chunkBytes.
422UPLOAD_TOO_LARGEMore data than the declared size.

Download a file

Files of any size, up to VAULTPANEL_FILE_DOWNLOAD_MAX_MB (2048 by default), are sent to the panel by the agent first, then downloaded from the panel. All three steps need files.read.

POST/api/v1/websites/:id/files/downloads
Auth
Session cookie (+ CSRF token) or API token
Permission
files.read
Token scope
manage
GET/api/v1/websites/:id/files/downloads/:downloadId
Auth
Session cookie (+ CSRF token) or API token
Permission
files.read
Token scope
manage
GET/api/v1/websites/:id/files/downloads/:downloadId/file
Auth
Session cookie (+ CSRF token) or API token
Permission
files.read
Token scope
manage
  1. Start with { path }. The panel answers 202 Accepted with a FILE_DOWNLOAD job that carries downloadId.
  2. Poll GET …/downloads/:downloadId until ready is true. It answers { id, path, ready, size, sha256 }.
  3. Fetch GET …/downloads/:downloadId/file. The file is sent as application/octet-stream with Content-Disposition: attachment (add ?inline=1 to leave that header out). Only the person who asked can fetch it, for an hour.
curl -L -o error.log \
  "https://panel.example.com/api/v1/websites/$SITE/files/downloads/$DOWNLOAD/file" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"

Errors

StatusCodeWhen
404NOT_FOUNDThe download expired, failed, or is not yours.
409DOWNLOAD_NOT_READYThe file is still on its way from the server.

Set up Git deploy

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

Turns Git deploy on for a static or PHP website, or changes its settings. Each deploy clones the repository and runs its install and build commands in a new release folder on the server, and the site serves that release's output folder. The newest releases stay for instant rollbacks. Turning it on (or moving to a repository on another host) sets up the release folder and a deploy key with a SITE_GIT_SETUP job; add the returned git.deployKey to the repository as a read-only deploy key. Needs agent 0.22.0 (0.32.0 for PHP sites) and Git on the server. See Git deploy.

Request body

FieldTypeRequiredDescription
repositoryUrlstringYesAn https:// or SSH Git URL, without a password in it. Up to 500 characters.
branchstringNoDefault main.
installCommandstring or nullNoUp to 10 lines of up to 500 characters, such as npm ci.
buildCommandstring or nullNoSame limits, such as npm run build.
outputDirstringNoThe folder to serve, inside the repository, such as dist. Empty serves the repository as it is.
keepReleasesintegerNoReleases to keep, 1 to 20. Default 5.
deployNowbooleanNoQueue the first deployment after setup. Default false.

Example request

curl -X PUT https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/git \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"repositoryUrl":"git@github.com:example/site.git","buildCommand":"npm ci\nnpm run build","outputDir":"dist","deployNow":true}'

Response 202 Accepted with { website, job, deployment } when a job is queued, or 200 OK when only settings were saved.

Errors

StatusCodeWhen
409WEBSITE_NOT_STATICThe site is a reverse proxy; its app deploys from Git itself.
409WEBSITE_OWNED_BY_APPThe site serves an app.
409AGENT_OUTDATEDThe agent is too old for Git deploy.
409SOFTWARE_MISSINGGit is not installed on the server.
409SERVER_NOT_READY, WEBSITE_BUSYSee above.
422VALIDATION_ERRORAn invalid URL, branch, command or folder.

Turn Git deploy off

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

Turns Git deploy off. When a release is live, the site serves its previous folder again (a job does that), and you manage it with the file manager.

Response 202 Accepted with { website, job }, or 200 OK with { website, job: null }.

Deploy a website from Git

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

Deploys the newest commit of the branch (DEPLOY_SITE_GIT).

Example request

curl -X POST https://panel.example.com/api/v1/websites/0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a/deploy \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"

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

Errors

StatusCodeWhen
409GIT_DEPLOY_OFFGit deploy is not on for this website.
409WEBSITE_BUSYAnother change is running.

Roll back a website

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

Makes an earlier release live again (ROLLBACK_SITE_GIT), without building it again.

Request body

FieldTypeRequiredDescription
deploymentIdstringYesA successful deployment whose release is still on the server.

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

Errors

StatusCodeWhen
404NOT_FOUNDNo such deployment of this website.
409WEBSITE_NOT_DEPLOYEDNothing was deployed from Git yet.
409RELEASE_ALREADY_LIVEThat release is already live.
409RELEASE_NOT_DEPLOYABLEThat deployment did not succeed.
409RELEASE_NOT_FOUNDIts release was removed (only the newest are kept). Deploy its commit again instead.

List website deployments

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

The website's 20 most recent Git deployments and rollbacks, newest first.

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "7c6b5a49-…",
        "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
        "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
        "jobId": "…",
        "kind": "deploy",
        "trigger": "webhook",
        "status": "succeeded",
        "releaseId": "20261110113000-a1b2c3",
        "sourceDeploymentId": null,
        "repositoryUrl": "git@github.com:example/site.git",
        "branch": "main",
        "outputDir": "dist",
        "commit": { "hash": "4e5f6a7b…", "message": "Update pricing page", "author": "Ada Lovelace" },
        "failedStage": null,
        "error": null,
        "releaseAvailable": true,
        "isCurrent": true,
        "requestedBy": null,
        "stages": null,
        "startedAt": "2026-11-10T11:30:00.000Z",
        "finishedAt": "2026-11-10T11:30:42.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

Get or set build variables

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

Environment variables available to a Git-deployed website's install and build commands. PUT replaces the whole list. Both answer { variables: [{ key, value }] }.

Request body (PUT)

FieldTypeRequiredDescription
variablesobject[]YesUp to 100 { key, value }. Keys are letters, digits and underscores, not starting with a digit; values up to 8192 characters.

Turn push to deploy on or off

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

POST creates (or replaces) the website's push webhook and returns its URL and signing secret, shown only this once. Add both to your Git host; a push to the branch then deploys the site through the Git push hook. DELETE turns it off.

Response 200 OK (POST)

{
  "success": true,
  "data": {
    "website": { "id": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a", "git": { "webhook": { "enabled": true, "signed": true, "createdAt": "…" } } },
    "webhook": { "url": "https://panel.example.com/api/v1/hooks/deploy/…", "secret": "…" }
  },
  "message": "Copy the webhook URL now: it is shown only once",
  "requestId": "…"
}

Errors

StatusCodeWhen
409GIT_DEPLOY_OFFGit deploy is not on for this website.

List subdomain parents

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

The domains a subdomain can be created under: those of your websites (every website's, for staff), without www. names and the panel's own domain.

Example request

curl https://panel.example.com/api/v1/subdomains/parents \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.subdomains.parents();

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "domain": "example.com",
        "website": { "id": "…", "name": "main" },
        "server": { "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "phpVersions": ["8.3"] },
        "customer": null
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

customer is shown to staff only.

Create a subdomain

POST/api/v1/subdomains
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.manage
Token scope
manage

Creates a website of its own for name.parentDomain, on the parent's server and owned by the parent's account, where it counts against the plan's subdomains. The site name is chosen for you. When a panel DNS zone holds the name, an A (and AAAA) record is added once the site exists and removed when it is deleted. Subdomains are websites: list, change and delete them with the website endpoints.

Request body

FieldTypeRequiredDescription
parentDomainstringYesOne of the domains from List subdomain parents.
namestringYesThe label to add, such as blog.
typestringYesstatic or php.
documentRootstringNoDefault public.
phpVersionstringFor phpA PHP version installed on the server.

Example request

curl https://panel.example.com/api/v1/subdomains \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"parentDomain":"example.com","name":"blog","type":"php","phpVersion":"8.3"}'
const { website, job } = await panel.subdomains.create({ parentDomain: 'example.com', name: 'blog', type: 'php', phpVersion: '8.3' });

Response 202 Accepted with { website, job }.

Errors

StatusCodeWhen
409NAME_TAKENNo free site name for the subdomain on that server.
409QUOTA_REACHEDThe plan allows no more subdomains.
422VALIDATION_ERRORparentDomain is not one of yours, or name is invalid.

List domains

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

Every domain of every website, alphabetically, with its site, server and whether HTTPS covers it. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
searchstringNoMatches the domain.
serverIdstringNoDomains on one server.
sortstringNodomain (default, ascending) or createdAt.

Example request

curl "https://panel.example.com/api/v1/domains?search=example" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.domains.list({ search: 'example' });

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "d4c3b2a1-…",
        "websiteId": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a",
        "domain": "shop.example.com",
        "isPrimary": true,
        "dns": null,
        "createdAt": "2026-11-01T10:00:00.000Z",
        "website": { "id": "0b8e4c2a-7d6f-4e1b-9a3c-5f2e8d1c4b7a", "name": "shop" },
        "server": { "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1" },
        "https": "active"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}

https is the covering certificate's state (active, expiring or expired), or null when no active certificate covers the domain.

Check a domain's DNS

POST/api/v1/domains/:id/dns-check
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.read
Token scope
read

The same check as Check a website's DNS, for one domain.

Response 200 OK with { items: [domain] }. 404 NOT_FOUND when there is no such domain.

List certificates

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

Certificates of every website, soonest expiry first. Supports the list parameters.

Query parameters

NameTypeRequiredDescription
statusstringNopending, active, failed, inactive, or expiring (active, inside the warning window) or expired.
serverIdstringNoCertificates on one server.
sortstringNonotAfter (default, ascending) or createdAt.

Example request

curl "https://panel.example.com/api/v1/ssl-certificates?status=expiring" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.certificates.list({ status: 'expiring' });

Response 200 OK: { items, pagination }. Each item is the website object's ssl with website: { id, name, status } and server: { id, name }.

Get renewal settings

GET/api/v1/ssl-certificates/renewal
Auth
Session cookie (+ CSRF token) or API token
Permission
websites.read
Token scope
read

When certificates renew and when they count as expiring. The panel renews a Let's Encrypt certificate itself when it is inside its renewal window and Certbot's timer has not.

Response 200 OK

{
  "success": true,
  "data": {
    "renewBeforeDays": 30,
    "warnDays": 14,
    "defaults": { "renewBeforeDays": 30, "warnDays": 14 },
    "limits": { "renewBeforeDays": { "min": 7, "max": 60 }, "warnDays": { "min": 1 } },
    "minAgentVersion": "0.25.0",
    "servers": [
      { "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "agentVersion": "0.41.0", "certificates": 6, "appliesWindow": true }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

servers lists the servers with certificates (empty for hosting customers). appliesWindow is false for agents older than 0.25.0, which keep Certbot's 30 days.

Change renewal settings

PUT/api/v1/ssl-certificates/renewal
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Saves the renewal window and applies it on every server with certificates whose agent can (SET_SSL_RENEWAL).

Request body

FieldTypeRequiredDescription
renewBeforeDaysintegerYesRenew this many days before expiry, 7 to 60.
warnDaysintegerYesShow certificates as expiring this many days before expiry. At least 1, and less than renewBeforeDays.

No other fields are accepted.

Example request

curl -X PUT https://panel.example.com/api/v1/ssl-certificates/renewal \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"renewBeforeDays":30,"warnDays":10}'

Response 200 OK: the same as Get renewal settings, plus queued ([{ serverId, name, jobId }]) and skipped ([{ serverId, name, reason }]).

Errors

StatusCodeWhen
422VALIDATION_ERRORA value out of range, warnDays not below renewBeforeDays, or an unknown field.