Websites
API reference for websites, SSL certificates, website files, uptime checks, Git deploy for static and PHP sites, subdomains and domains.
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
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/websites | List websites |
| POST | /api/v1/websites | Create a website |
| GET | /api/v1/websites/:id | Get a website |
| PATCH | /api/v1/websites/:id | Update a website |
| DELETE | /api/v1/websites/:id | Delete a website |
| POST | /api/v1/websites/:id/enable | Enable or disable a website |
| POST | /api/v1/websites/:id/disable | Enable or disable a website |
| POST | /api/v1/websites/:id/retry | Retry creating a website |
| POST | /api/v1/websites/:id/ssl | Issue a Let's Encrypt certificate |
| POST | /api/v1/websites/:id/ssl/upload | Install your own certificate |
| POST | /api/v1/websites/:id/ssl/renew | Renew a certificate |
| DELETE | /api/v1/websites/:id/ssl | Turn HTTPS off |
| POST | /api/v1/websites/:id/logs | Read website logs |
| POST | /api/v1/websites/:id/dns-check | Check a website's DNS |
| GET | /api/v1/websites/:id/uptime | Get uptime |
| PUT | /api/v1/websites/:id/uptime | Turn uptime monitoring on or off |
| POST | /api/v1/websites/:id/uptime/check | Check uptime now |
| POST | /api/v1/websites/:id/files/:action | Run a file action |
| POST | /api/v1/websites/:id/files/uploads | Upload a large file |
| PUT | /api/v1/websites/:id/files/uploads/:uploadId/chunks/:offset | Upload a large file |
| POST | /api/v1/websites/:id/files/uploads/:uploadId/finish | Upload a large file |
| POST | /api/v1/websites/:id/files/downloads | Download a file |
| GET | /api/v1/websites/:id/files/downloads/:downloadId | Download a file |
| GET | /api/v1/websites/:id/files/downloads/:downloadId/file | Download a file |
| PUT | /api/v1/websites/:id/git | Set up Git deploy |
| DELETE | /api/v1/websites/:id/git | Turn Git deploy off |
| POST | /api/v1/websites/:id/deploy | Deploy a website from Git |
| POST | /api/v1/websites/:id/rollback | Roll back a website |
| GET | /api/v1/websites/:id/deployments | List website deployments |
| GET | /api/v1/websites/:id/environment | Get or set build variables |
| PUT | /api/v1/websites/:id/environment | Get or set build variables |
| POST | /api/v1/websites/:id/git/webhook | Turn push to deploy on or off |
| DELETE | /api/v1/websites/:id/git/webhook | Turn push to deploy on or off |
| GET | /api/v1/subdomains/parents | List subdomain parents |
| POST | /api/v1/subdomains | Create a subdomain |
| GET | /api/v1/domains | List domains |
| POST | /api/v1/domains/:id/dns-check | Check a domain's DNS |
| GET | /api/v1/ssl-certificates | List certificates |
| GET | /api/v1/ssl-certificates/renewal | Get renewal settings |
| PUT | /api/v1/ssl-certificates/renewal | Change 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"
}| Field | Description |
|---|---|
type | static, php or proxy. |
status | creating, active, updating, disabled, deleting or failed. |
domains | The first is the primary domain. dns.status is ok (points at the server), mismatch, unresolved or error, after a DNS check. |
documentRoot | The folder inside the site that is served, such as public. |
customNginx, htaccess, spa | Custom NGINX rules, .htaccess support through Apache, and the single-page app setting (static sites). See NGINX rules and .htaccess. |
health | The agent's check right after the last change: status is ok or failing. |
uptime | The panel's own uptime checks. Get uptime has more. |
ssl | The certificate, or null. status is pending, active, failed or inactive; state adds expiring and expired. provider is letsencrypt or custom (uploaded). |
application | The app this site serves as a reverse proxy, or null. |
git | Git deploy settings, or null while the site is managed with the file manager. See Set up Git deploy. |
uncoveredDomains | Domains added after the active certificate was issued, which it does not cover. |
subdomainOf, dnsRecords | For sites added as subdomains: the parent domain and the DNS records the panel added. |
List websites
/api/v1/websitesWebsites, newest first. Hosting customers see only their own. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches the site name or any of its domains. |
serverId | string | No | Sites on one server. |
status | string | No | One of the statuses above. |
subdomains | boolean | No | true lists only sites added as subdomains. |
sort | string | No | createdAt (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
/api/v1/websitesSaves 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
| Field | Type | Required | Description |
|---|---|---|---|
serverId | string | Yes | The server to create it on. |
name | string | Yes | 3 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. |
type | string | Yes | static, php or proxy. |
domains | string[] | Yes | 1 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). |
documentRoot | string | No | The folder inside the site to serve. Default public. |
phpVersion | string | For php | A PHP version installed on the server, such as 8.3. |
proxyPort | integer | For proxy | The 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
| Status | Code | When |
|---|---|---|
| 409 | SERVER_NOT_READY | The server has no connected agent yet. |
| 409 | NGINX_NOT_INSTALLED | Install the web stack on the server first. |
| 409 | AGENT_OUTDATED | A wildcard domain needs agent 0.37.0 or later. |
| 409 | QUOTA_REACHED | A hosting customer's plan allows no more websites. |
| 422 | VALIDATION_ERROR | An invalid field, a name or domain already taken, a missing phpVersion or proxyPort, or a server that was not found. |
Get a website
/api/v1/websites/:idThe 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such website, or not yours. |
Update a website
/api/v1/websites/:idChanges 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
| Field | Type | Required | Description |
|---|---|---|---|
type | string | No | static, php or proxy. |
domains | string[] | No | The full new list, 1 to 20; the first is primary. |
documentRoot | string | No | The folder to serve. |
phpVersion | string or null | No | For PHP sites. |
proxyPort | integer or null | No | For reverse proxies. |
forceHttps | boolean | No | Redirect HTTP to HTTPS. Needs an active certificate. |
customNginx | string | No | Custom NGINX rules for the site's server block, up to 8192 characters. Staff only; needs agent 0.18.0. |
htaccess | boolean | No | Honour .htaccess files through Apache behind NGINX. Needs agent 0.18.0. |
spa | boolean | No | Static 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | A hosting customer sent customNginx. |
| 409 | WEBSITE_BUSY | Another change is running (details.jobId). |
| 409 | WEBSITE_NOT_READY | The site was never created on its server. Retry or delete it. |
| 409 | WEBSITE_OWNED_BY_APP | The site serves an app; change the app's port instead. |
| 409 | WEBSITE_GIT_DEPLOY | The site deploys from Git; turn Git deploy off before changing its type. |
| 409 | PANEL_WEBSITE | The site serves the panel's own domain. Change it on the Panel Domain page. |
| 409 | AGENT_OUTDATED | The setting needs a newer agent. |
| 422 | VALIDATION_ERROR | An invalid value, forceHttps without a certificate, or nothing to update. |
Delete a website
/api/v1/websites/:idRemoves 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
| Name | Type | Required | Description |
|---|---|---|---|
removeFiles | boolean | No | Also 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
| Status | Code | When |
|---|---|---|
| 409 | WEBSITE_BUSY | Another change is running. |
| 409 | WEBSITE_OWNED_BY_APP | removeFiles=true on a site that serves an app: the files belong to the app. |
| 409 | PANEL_WEBSITE | The site serves the panel's own domain. |
Enable or disable a website
/api/v1/websites/:id/enable/api/v1/websites/:id/disableA 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
/api/v1/websites/:id/retryQueues CREATE_SITE again for a website whose creation failed.
Response 202 Accepted with { website, job }.
Errors
| Status | Code | When |
|---|---|---|
| 409 | WEBSITE_READY | The website already exists on its server. |
| 409 | WEBSITE_BUSY | Another change is running. |
Issue a Let's Encrypt certificate
/api/v1/websites/:id/sslRequests 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
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Let's Encrypt's contact address for expiry notices. |
staging | boolean | No | Use Let's Encrypt's staging service, for a test certificate browsers do not trust. Default false. |
verifyDns | boolean | No | Check the domains point at the server first. Default true. |
forceHttps | boolean | No | Redirect HTTP to HTTPS once issued. Default true. |
wildcard | boolean | No | Ask for a wildcard certificate through the server's DNS zone. Default false. |
dnsProviderId | string or null | No | A 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
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | dnsProviderId from a hosting customer, or without dns.read. |
| 409 | SITE_DISABLED | Enable the website first. |
| 409 | CERTBOT_NOT_INSTALLED | Install Certbot from the server's web stack first. |
| 409 | DNS_ZONE_MISSING | A wildcard certificate needs a DNS zone for the domain on this server. |
| 409 | AGENT_OUTDATED | Wildcard certificates need agent 0.28.0, DNS providers 0.38.0. |
| 409 | DNS_PROVIDER_NO_ADDRESS | Namecheap needs the server's public IPv4 address, which the panel does not know. |
| 409 | WEBSITE_BUSY, WEBSITE_NOT_READY | See Update a website. |
| 422 | WILDCARD_NOT_POSSIBLE | The site's domains do not fit one wildcard certificate. |
| 422 | DNS_PROVIDER_DOMAIN | The panel cannot tell which Namecheap domain the name belongs to. |
Install your own certificate
/api/v1/websites/:id/ssl/uploadInstalls 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
| Field | Type | Required | Description |
|---|---|---|---|
certificate | string | Yes | PEM certificate with its chain, up to 65536 characters. |
privateKey | string | Yes | PEM private key, up to 16384 characters. |
forceHttps | boolean | No | Redirect 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
| Status | Code | When |
|---|---|---|
| 409 | AGENT_OUTDATED | The agent is older than 0.28.0. |
| 409 | WEBSITE_BUSY, WEBSITE_NOT_READY | See Update a website. |
| 422 | VALIDATION_ERROR | The PEM data is missing or not a certificate and key. |
Renew a certificate
/api/v1/websites/:id/ssl/renewRenews 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
| Field | Type | Required | Description |
|---|---|---|---|
force | boolean | No | Renew 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
| Status | Code | When |
|---|---|---|
| 409 | SSL_NOT_FOUND | The site has no certificate yet. |
| 409 | SSL_CUSTOM | The certificate was uploaded; upload the renewed one instead. |
| 409 | WEBSITE_BUSY | Another change is running. |
Turn HTTPS off
/api/v1/websites/:id/sslServes 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
| Status | Code | When |
|---|---|---|
| 409 | SSL_NOT_ACTIVE | HTTPS is not on for this website. |
Read website logs
/api/v1/websites/:id/logsQueues 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
| Field | Type | Required | Description |
|---|---|---|---|
log | string | Yes | access or error. |
lines | integer | No | 10 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
| Status | Code | When |
|---|---|---|
| 409 | WEBSITE_NOT_READY | The site does not exist on its server yet. |
Check a website's DNS
/api/v1/websites/:id/dns-checkLooks 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
/api/v1/websites/:id/uptimeThe 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
/api/v1/websites/:id/uptimeTurning monitoring off forgets the current status and ends any open downtime, so its Website down alert resolves.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | Check 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
/api/v1/websites/:id/uptime/checkChecks the website once, now, without the second try.
Response 200 OK, the same as Get uptime, message Checked.
Errors
| Status | Code | When |
|---|---|---|
| 409 | UPTIME_NOT_CHECKED | Monitoring is off for this website, or the website is disabled. |
Run a file action
/api/v1/websites/:id/files/:actionThe 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.
| Action | Body | What it does |
|---|---|---|
list | path (default "", the home folder) | Lists a folder. |
read | path | Reads a file up to 1 MB. |
write | path, content, encoding (utf8 or base64, default utf8), overwrite (default true) | Saves a file up to 1 MB. |
mkdir | path | Creates a folder. |
rename | from, to | Renames or moves a file or folder. |
delete | path | Deletes a file or folder. |
extract | path (a .zip, .tar.gz, .tgz or .tar), to (default ""), overwrite (default false) | Unpacks an archive; to is created when missing. |
compress | folder (default ""), names (1 to 200 names in the folder), to (a path ending in .zip) | Makes a zip. |
chmod | path, 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
| Status | Code | When |
|---|---|---|
| 409 | WEBSITE_NOT_READY | The site's files are not available (being created or deleted). |
| 422 | VALIDATION_ERROR | Unknown 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:
/api/v1/websites/:id/files/uploads/api/v1/websites/:id/files/uploads/:uploadId/chunks/:offset/api/v1/websites/:id/files/uploads/:uploadId/finish- Start with
{ path, size, overwrite }(overwritedefaults tofalse). The panel answers201 Createdwith{ uploadId, chunkBytes, size }. - Send the pieces in order as raw bytes (
Content-Type: application/octet-stream), each up tochunkBytes(8 MB), at the byte offset it starts at. Each answers{ received, size }. - Finish. The panel answers
202 Acceptedwith aFILE_UPLOADjob: 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
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | A piece arrived without a body. |
| 404 | NOT_FOUND | No such upload, or it is not yours. |
| 409 | OFFSET_MISMATCH | The piece does not start where the last one ended (details.expected). |
| 409 | UPLOAD_INCOMPLETE | Finished before every byte arrived (details.received). |
| 409 | UPLOAD_FINISHED | The upload is already complete. |
| 413 | FILE_TOO_LARGE | size is over the panel's upload limit. |
| 413 | CHUNK_TOO_LARGE | A piece is larger than chunkBytes. |
| 422 | UPLOAD_TOO_LARGE | More 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.
/api/v1/websites/:id/files/downloads/api/v1/websites/:id/files/downloads/:downloadId/api/v1/websites/:id/files/downloads/:downloadId/file- Start with
{ path }. The panel answers202 Acceptedwith aFILE_DOWNLOADjob that carriesdownloadId. - Poll
GET …/downloads/:downloadIduntilreadyistrue. It answers{ id, path, ready, size, sha256 }. - Fetch
GET …/downloads/:downloadId/file. The file is sent asapplication/octet-streamwithContent-Disposition: attachment(add?inline=1to 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
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | The download expired, failed, or is not yours. |
| 409 | DOWNLOAD_NOT_READY | The file is still on its way from the server. |
Set up Git deploy
/api/v1/websites/:id/gitTurns 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
| Field | Type | Required | Description |
|---|---|---|---|
repositoryUrl | string | Yes | An https:// or SSH Git URL, without a password in it. Up to 500 characters. |
branch | string | No | Default main. |
installCommand | string or null | No | Up to 10 lines of up to 500 characters, such as npm ci. |
buildCommand | string or null | No | Same limits, such as npm run build. |
outputDir | string | No | The folder to serve, inside the repository, such as dist. Empty serves the repository as it is. |
keepReleases | integer | No | Releases to keep, 1 to 20. Default 5. |
deployNow | boolean | No | Queue 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
| Status | Code | When |
|---|---|---|
| 409 | WEBSITE_NOT_STATIC | The site is a reverse proxy; its app deploys from Git itself. |
| 409 | WEBSITE_OWNED_BY_APP | The site serves an app. |
| 409 | AGENT_OUTDATED | The agent is too old for Git deploy. |
| 409 | SOFTWARE_MISSING | Git is not installed on the server. |
| 409 | SERVER_NOT_READY, WEBSITE_BUSY | See above. |
| 422 | VALIDATION_ERROR | An invalid URL, branch, command or folder. |
Turn Git deploy off
/api/v1/websites/:id/gitTurns 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
/api/v1/websites/:id/deployDeploys 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
| Status | Code | When |
|---|---|---|
| 409 | GIT_DEPLOY_OFF | Git deploy is not on for this website. |
| 409 | WEBSITE_BUSY | Another change is running. |
Roll back a website
/api/v1/websites/:id/rollbackMakes an earlier release live again (ROLLBACK_SITE_GIT), without building it again.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
deploymentId | string | Yes | A successful deployment whose release is still on the server. |
Response 202 Accepted with { website, deployment, job }.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such deployment of this website. |
| 409 | WEBSITE_NOT_DEPLOYED | Nothing was deployed from Git yet. |
| 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 (only the newest are kept). Deploy its commit again instead. |
List website deployments
/api/v1/websites/:id/deploymentsThe 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
/api/v1/websites/:id/environment/api/v1/websites/:id/environmentEnvironment 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)
| Field | Type | Required | Description |
|---|---|---|---|
variables | object[] | Yes | Up 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
/api/v1/websites/:id/git/webhook/api/v1/websites/:id/git/webhookPOST 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
| Status | Code | When |
|---|---|---|
| 409 | GIT_DEPLOY_OFF | Git deploy is not on for this website. |
List subdomain parents
/api/v1/subdomains/parentsThe 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
/api/v1/subdomainsCreates 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
| Field | Type | Required | Description |
|---|---|---|---|
parentDomain | string | Yes | One of the domains from List subdomain parents. |
name | string | Yes | The label to add, such as blog. |
type | string | Yes | static or php. |
documentRoot | string | No | Default public. |
phpVersion | string | For php | A 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
| Status | Code | When |
|---|---|---|
| 409 | NAME_TAKEN | No free site name for the subdomain on that server. |
| 409 | QUOTA_REACHED | The plan allows no more subdomains. |
| 422 | VALIDATION_ERROR | parentDomain is not one of yours, or name is invalid. |
List domains
/api/v1/domainsEvery domain of every website, alphabetically, with its site, server and whether HTTPS covers it. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Matches the domain. |
serverId | string | No | Domains on one server. |
sort | string | No | domain (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
/api/v1/domains/:id/dns-checkThe 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
/api/v1/ssl-certificatesCertificates of every website, soonest expiry first. Supports the list parameters.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | pending, active, failed, inactive, or expiring (active, inside the warning window) or expired. |
serverId | string | No | Certificates on one server. |
sort | string | No | notAfter (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
/api/v1/ssl-certificates/renewalWhen 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
/api/v1/ssl-certificates/renewalSaves the renewal window and applies it on every server with certificates whose agent can (SET_SSL_RENEWAL).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
renewBeforeDays | integer | Yes | Renew this many days before expiry, 7 to 60. |
warnDays | integer | Yes | Show 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
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | A value out of range, warnDays not below renewBeforeDays, or an unknown field. |
Security
API reference for server firewalls, SSH settings and keys, Fail2ban, security updates, the login message, panel access by address, two-factor policy and sessions.
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.