# Websites

URL: https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/guides/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`](https://docs.vaultpanel.net/api-reference/jobs#get-a-job-and-its-logs) for it.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/websites` | [List websites](https://docs.vaultpanel.net/api-reference/websites#list-websites) |
| POST | `/api/v1/websites` | [Create a website](https://docs.vaultpanel.net/api-reference/websites#create-a-website) |
| GET | `/api/v1/websites/:id` | [Get a website](https://docs.vaultpanel.net/api-reference/websites#get-a-website) |
| PATCH | `/api/v1/websites/:id` | [Update a website](https://docs.vaultpanel.net/api-reference/websites#update-a-website) |
| DELETE | `/api/v1/websites/:id` | [Delete a website](https://docs.vaultpanel.net/api-reference/websites#delete-a-website) |
| POST | `/api/v1/websites/:id/enable` | [Enable or disable a website](https://docs.vaultpanel.net/api-reference/websites#enable-or-disable-a-website) |
| POST | `/api/v1/websites/:id/disable` | [Enable or disable a website](https://docs.vaultpanel.net/api-reference/websites#enable-or-disable-a-website) |
| POST | `/api/v1/websites/:id/retry` | [Retry creating a website](https://docs.vaultpanel.net/api-reference/websites#retry-creating-a-website) |
| POST | `/api/v1/websites/:id/ssl` | [Issue a Let's Encrypt certificate](https://docs.vaultpanel.net/api-reference/websites#issue-a-lets-encrypt-certificate) |
| POST | `/api/v1/websites/:id/ssl/upload` | [Install your own certificate](https://docs.vaultpanel.net/api-reference/websites#install-your-own-certificate) |
| POST | `/api/v1/websites/:id/ssl/renew` | [Renew a certificate](https://docs.vaultpanel.net/api-reference/websites#renew-a-certificate) |
| DELETE | `/api/v1/websites/:id/ssl` | [Turn HTTPS off](https://docs.vaultpanel.net/api-reference/websites#turn-https-off) |
| POST | `/api/v1/websites/:id/logs` | [Read website logs](https://docs.vaultpanel.net/api-reference/websites#read-website-logs) |
| POST | `/api/v1/websites/:id/dns-check` | [Check a website's DNS](https://docs.vaultpanel.net/api-reference/websites#check-a-websites-dns) |
| GET | `/api/v1/websites/:id/uptime` | [Get uptime](https://docs.vaultpanel.net/api-reference/websites#get-uptime) |
| PUT | `/api/v1/websites/:id/uptime` | [Turn uptime monitoring on or off](https://docs.vaultpanel.net/api-reference/websites#turn-uptime-monitoring-on-or-off) |
| POST | `/api/v1/websites/:id/uptime/check` | [Check uptime now](https://docs.vaultpanel.net/api-reference/websites#check-uptime-now) |
| POST | `/api/v1/websites/:id/files/:action` | [Run a file action](https://docs.vaultpanel.net/api-reference/websites#run-a-file-action) |
| POST | `/api/v1/websites/:id/files/uploads` | [Upload a large file](https://docs.vaultpanel.net/api-reference/websites#upload-a-large-file) |
| PUT | `/api/v1/websites/:id/files/uploads/:uploadId/chunks/:offset` | [Upload a large file](https://docs.vaultpanel.net/api-reference/websites#upload-a-large-file) |
| POST | `/api/v1/websites/:id/files/uploads/:uploadId/finish` | [Upload a large file](https://docs.vaultpanel.net/api-reference/websites#upload-a-large-file) |
| POST | `/api/v1/websites/:id/files/downloads` | [Download a file](https://docs.vaultpanel.net/api-reference/websites#download-a-file) |
| GET | `/api/v1/websites/:id/files/downloads/:downloadId` | [Download a file](https://docs.vaultpanel.net/api-reference/websites#download-a-file) |
| GET | `/api/v1/websites/:id/files/downloads/:downloadId/file` | [Download a file](https://docs.vaultpanel.net/api-reference/websites#download-a-file) |
| PUT | `/api/v1/websites/:id/git` | [Set up Git deploy](https://docs.vaultpanel.net/api-reference/websites#set-up-git-deploy) |
| DELETE | `/api/v1/websites/:id/git` | [Turn Git deploy off](https://docs.vaultpanel.net/api-reference/websites#turn-git-deploy-off) |
| POST | `/api/v1/websites/:id/deploy` | [Deploy a website from Git](https://docs.vaultpanel.net/api-reference/websites#deploy-a-website-from-git) |
| POST | `/api/v1/websites/:id/rollback` | [Roll back a website](https://docs.vaultpanel.net/api-reference/websites#roll-back-a-website) |
| GET | `/api/v1/websites/:id/deployments` | [List website deployments](https://docs.vaultpanel.net/api-reference/websites#list-website-deployments) |
| GET | `/api/v1/websites/:id/environment` | [Get or set build variables](https://docs.vaultpanel.net/api-reference/websites#get-or-set-build-variables) |
| PUT | `/api/v1/websites/:id/environment` | [Get or set build variables](https://docs.vaultpanel.net/api-reference/websites#get-or-set-build-variables) |
| POST | `/api/v1/websites/:id/git/webhook` | [Turn push to deploy on or off](https://docs.vaultpanel.net/api-reference/websites#turn-push-to-deploy-on-or-off) |
| DELETE | `/api/v1/websites/:id/git/webhook` | [Turn push to deploy on or off](https://docs.vaultpanel.net/api-reference/websites#turn-push-to-deploy-on-or-off) |
| GET | `/api/v1/subdomains/parents` | [List subdomain parents](https://docs.vaultpanel.net/api-reference/websites#list-subdomain-parents) |
| POST | `/api/v1/subdomains` | [Create a subdomain](https://docs.vaultpanel.net/api-reference/websites#create-a-subdomain) |
| GET | `/api/v1/domains` | [List domains](https://docs.vaultpanel.net/api-reference/websites#list-domains) |
| POST | `/api/v1/domains/:id/dns-check` | [Check a domain's DNS](https://docs.vaultpanel.net/api-reference/websites#check-a-domains-dns) |
| GET | `/api/v1/ssl-certificates` | [List certificates](https://docs.vaultpanel.net/api-reference/websites#list-certificates) |
| GET | `/api/v1/ssl-certificates/renewal` | [Get renewal settings](https://docs.vaultpanel.net/api-reference/websites#get-renewal-settings) |
| PUT | `/api/v1/ssl-certificates/renewal` | [Change renewal settings](https://docs.vaultpanel.net/api-reference/websites#change-renewal-settings) |

## The website object

```json
{
  "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](https://docs.vaultpanel.net/guides/websites/nginx-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](https://docs.vaultpanel.net/api-reference/websites#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](https://docs.vaultpanel.net/api-reference/websites#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](https://docs.vaultpanel.net/api-reference/websites#create-a-subdomain): the parent domain and the DNS records the panel added. |

## List websites

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

Websites, newest first. Hosting customers see only their own. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**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**

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

**JavaScript**

```js
const { items } = await panel.websites.list({ search: 'example.com' });
```

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

## Create a website

`POST /api/v1/websites` — 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**

| 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**

```bash
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"
  }'
```

**JavaScript**

```js
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`

```json
{
  "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

`GET /api/v1/websites/:id` — 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**

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

**JavaScript**

```js
const website = await panel.websites.get(websiteId);
```

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

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such website, or not yours. |

## Update a website

`PATCH /api/v1/websites/:id` — 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**

| 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**

```bash
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}'
```

**JavaScript**

```js
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

`DELETE /api/v1/websites/:id` — 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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `removeFiles` | boolean | No | Also delete the site's folder and Linux user. Default `false`. |

**Example request**

**cURL**

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

**JavaScript**

```js
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

`POST /api/v1/websites/:id/enable` — Permission: websites.manage — Token scope: manage

`POST /api/v1/websites/:id/disable` — Permission: websites.manage — Token scope: manage

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

**Example request**

**cURL**

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

**JavaScript**

```js
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](https://docs.vaultpanel.net/api-reference/websites#update-a-website).

## Retry creating a website

`POST /api/v1/websites/:id/retry` — Permission: websites.manage — Token scope: manage

Queues `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

`POST /api/v1/websites/:id/ssl` — 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](https://docs.vaultpanel.net/guides/websites/ssl-certificates).

**Wildcard certificates.** With `wildcard: true`, one certificate covers the domain and `*.domain`, checked through DNS: the domain needs an active [DNS zone](https://docs.vaultpanel.net/guides/dns-and-email/dns-zones) on the site's server. Or pass `dnsProviderId` to check it through [Cloudflare or Namecheap](https://docs.vaultpanel.net/guides/dns-and-email/dns-providers) 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**

```bash
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}'
```

**JavaScript**

```js
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](https://docs.vaultpanel.net/api-reference/websites#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

`POST /api/v1/websites/:id/ssl/upload` — 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**

| 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**

```bash
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](https://docs.vaultpanel.net/api-reference/websites#update-a-website). |
| 422 | `VALIDATION_ERROR` | The PEM data is missing or not a certificate and key. |

## Renew a certificate

`POST /api/v1/websites/:id/ssl/renew` — 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](https://docs.vaultpanel.net/api-reference/websites#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**

```bash
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}'
```

**JavaScript**

```js
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

`DELETE /api/v1/websites/:id/ssl` — 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**

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

**JavaScript**

```js
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

`POST /api/v1/websites/:id/logs` — 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**

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

**Example request**

**cURL**

```bash
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}'
```

**JavaScript**

```js
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

`POST /api/v1/websites/:id/dns-check` — 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**

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

**JavaScript**

```js
const { items } = await panel.websites.checkDns(websiteId);
```

**Response** `200 OK`

```json
{
  "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` — 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](https://docs.vaultpanel.net/guides/websites/uptime-monitoring).

**Example request**

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

**Response** `200 OK`

```json
{
  "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` — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | Check this website. |

**Example request**

```bash
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](https://docs.vaultpanel.net/api-reference/websites#get-uptime).

## Check uptime now

`POST /api/v1/websites/:id/uptime/check` — Permission: websites.manage — Token scope: manage

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

**Response** `200 OK`, the same as [Get uptime](https://docs.vaultpanel.net/api-reference/websites#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

`POST /api/v1/websites/:id/files/:action` — 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](https://docs.vaultpanel.net/api-reference/websites#upload-a-large-file) and [Download a file](https://docs.vaultpanel.net/api-reference/websites#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**

```bash
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"}'
```

**JavaScript**

```js
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:

```json
{
  "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`:

`POST /api/v1/websites/:id/files/uploads` — Permission: files.write — Token scope: manage

`PUT /api/v1/websites/:id/files/uploads/:uploadId/chunks/:offset` — Permission: files.write — Token scope: manage

`POST /api/v1/websites/:id/files/uploads/:uploadId/finish` — 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.

```bash
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`.

`POST /api/v1/websites/:id/files/downloads` — Permission: files.read — Token scope: manage

`GET /api/v1/websites/:id/files/downloads/:downloadId` — Permission: files.read — Token scope: manage

`GET /api/v1/websites/:id/files/downloads/:downloadId/file` — 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.

```bash
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

`PUT /api/v1/websites/:id/git` — 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](https://docs.vaultpanel.net/guides/websites/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**

```bash
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

`DELETE /api/v1/websites/:id/git` — 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` — Permission: websites.manage — Token scope: manage

Deploys the newest commit of the branch (`DEPLOY_SITE_GIT`).

**Example request**

```bash
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

`POST /api/v1/websites/:id/rollback` — Permission: websites.manage — Token scope: manage

Makes 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

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

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

**Response** `200 OK`

```json
{
  "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` — Permission: websites.manage — Token scope: manage

`PUT /api/v1/websites/:id/environment` — 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`)

| 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

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

`DELETE /api/v1/websites/:id/git/webhook` — 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](https://docs.vaultpanel.net/api-reference/applications#git-push-hook). `DELETE` turns it off.

**Response** `200 OK` (`POST`)

```json
{
  "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

`GET /api/v1/subdomains/parents` — 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**

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

**JavaScript**

```js
const { items } = await panel.subdomains.parents();
```

**Response** `200 OK`

```json
{
  "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` — 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](https://docs.vaultpanel.net/guides/dns-and-email/dns-zones) 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](https://docs.vaultpanel.net/api-reference/websites#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**

```bash
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"}'
```

**JavaScript**

```js
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

`GET /api/v1/domains` — 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](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**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**

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

**JavaScript**

```js
const { items } = await panel.domains.list({ search: 'example' });
```

**Response** `200 OK`

```json
{
  "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` — Permission: websites.read — Token scope: read

The same check as [Check a website's DNS](https://docs.vaultpanel.net/api-reference/websites#check-a-websites-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` — Permission: websites.read — Token scope: read

Certificates of every website, soonest expiry first. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**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**

```bash
curl "https://panel.example.com/api/v1/ssl-certificates?status=expiring" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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` — 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`

```json
{
  "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` — 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**

| 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**

```bash
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](https://docs.vaultpanel.net/api-reference/websites#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. |
