# DNS

URL: https://docs.vaultpanel.net/api-reference/dns

> API reference for DNS zones served by BIND on your servers, their records, customer name servers and the Cloudflare and Namecheap DNS providers.

DNS zones are served by BIND on one of the panel's servers. The panel keeps each zone's records: every change raises the zone's serial and sends the whole zone to the server in a `DNS_ZONE_APPLY` job, and a zone whose records would not load is refused before it is sent. DNS providers hold Cloudflare or Namecheap credentials used to issue wildcard certificates for domains whose DNS is hosted there.

`/dns` is for staff: hosting customers are refused with `403 FORBIDDEN` and see their own zones through [`GET /api/v1/hosting/me/dns`](https://docs.vaultpanel.net/api-reference/hosting#get-your-dns). For concepts and the panel workflow, see [DNS zones](https://docs.vaultpanel.net/guides/dns-and-email/dns-zones) and [DNS providers](https://docs.vaultpanel.net/guides/dns-and-email/dns-providers).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/dns/zones` | [List zones](https://docs.vaultpanel.net/api-reference/dns#list-zones) |
| POST | `/api/v1/dns/zones` | [Create a zone](https://docs.vaultpanel.net/api-reference/dns#create-a-zone) |
| GET | `/api/v1/dns/zones/:id` | [Get a zone](https://docs.vaultpanel.net/api-reference/dns#get-a-zone) |
| PATCH | `/api/v1/dns/zones/:id` | [Update a zone](https://docs.vaultpanel.net/api-reference/dns#update-a-zone) |
| DELETE | `/api/v1/dns/zones/:id` | [Delete a zone](https://docs.vaultpanel.net/api-reference/dns#delete-a-zone) |
| POST | `/api/v1/dns/zones/:id/apply` | [Apply a zone again](https://docs.vaultpanel.net/api-reference/dns#apply-a-zone-again) |
| POST | `/api/v1/dns/zones/:id/check` | [Check name servers in public DNS](https://docs.vaultpanel.net/api-reference/dns#check-name-servers-in-public-dns) |
| POST | `/api/v1/dns/zones/:id/records` | [Add a record](https://docs.vaultpanel.net/api-reference/dns#add-a-record) |
| PATCH | `/api/v1/dns/zones/:id/records/:recordId` | [Update a record](https://docs.vaultpanel.net/api-reference/dns#update-a-record) |
| DELETE | `/api/v1/dns/zones/:id/records/:recordId` | [Delete a record](https://docs.vaultpanel.net/api-reference/dns#delete-a-record) |
| PUT | `/api/v1/dns/servers/:id/customers` | [Set customer name servers](https://docs.vaultpanel.net/api-reference/dns#set-customer-name-servers) |
| GET | `/api/v1/dns/providers` | [List DNS providers](https://docs.vaultpanel.net/api-reference/dns#list-dns-providers) |
| POST | `/api/v1/dns/providers` | [Add a DNS provider](https://docs.vaultpanel.net/api-reference/dns#add-a-dns-provider) |
| GET | `/api/v1/dns/providers/:id` | [Get a DNS provider](https://docs.vaultpanel.net/api-reference/dns#get-a-dns-provider) |
| PUT | `/api/v1/dns/providers/:id` | [Update a DNS provider](https://docs.vaultpanel.net/api-reference/dns#update-a-dns-provider) |
| DELETE | `/api/v1/dns/providers/:id` | [Delete a DNS provider](https://docs.vaultpanel.net/api-reference/dns#delete-a-dns-provider) |

## The zone object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (UUID) | Zone id. |
| `serverId`, `serverName` | string | The server whose BIND serves the zone. |
| `domain` | string | The zone's domain, such as `example.com`. |
| `customerId` | string or null | The hosting account the zone was added for automatically, if any. |
| `status` | string | `creating` (first apply running), `active`, `failed` (first apply failed) or `deleting`. |
| `defaultTtl` | integer | Default TTL in seconds. |
| `soaEmail` | string | The SOA contact address (`hostmaster@<domain>` unless set). |
| `serial`, `appliedSerial` | integer | The zone's serial, and the serial the server confirmed. |
| `appliedAt` | string or null | When the server last confirmed the zone. |
| `pending` | boolean | `true` while the server does not have the latest changes yet. |
| `applying` | boolean | `true` while a `DNS_ZONE_APPLY` job is queued or running. |
| `recordCount` | integer | Number of records. |
| `records` | array | Only on single-zone responses: every [record](https://docs.vaultpanel.net/api-reference/dns#the-record-object). |
| `nameservers` | array | Only on single-zone responses: the zone's `@` NS records as `{ host, inZone, addresses }`, what to enter at the registrar. |
| `delegation` | object or null | The last [name server check](https://docs.vaultpanel.net/api-reference/dns#check-name-servers-in-public-dns): `{ status, nameservers, detail, checkedAt }`. |
| `lastJobId` | string or null | The last job sent for the zone. |
| `lastError` | object or null | `{ code, message }` of the last failed job. |
| `createdAt`, `updatedAt` | string | ISO 8601 timestamps. |

## The record object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (UUID) | Record id. |
| `name` | string | Name relative to the zone: `@` for the domain itself, `www`, `mail`… |
| `fullName` | string | The full name, such as `www.example.com`. |
| `type` | string | `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV` or `CAA`. |
| `ttl` | integer or null | TTL in seconds, or `null` for the zone's default. |
| `value` | string | Address, host name or text. |
| `priority` | integer or null | `MX` and `SRV` only. |
| `weight`, `port` | integer or null | `SRV` only. |
| `tag` | string or null | `CAA` only: `issue`, `issuewild` or `iodef`. |

## List zones

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

Returns zones a page at a time, without their records (`recordCount` gives the number).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | No | Part of the domain, up to 100 characters. |
| `serverId` | string (UUID) | No | Only zones on this server. |
| `page`, `pageSize` | integer | No | Page number from 1, and 1 to 100 items per page (default 25). |
| `sort` | string | No | `domain` (default) or `createdAt`. |
| `order` | string | No | `asc` (default) or `desc`. |

**Example request**

**cURL**

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

**JavaScript**

```js
const { items, pagination } = await panel.dns.zones({ search: 'example' });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f",
        "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "serverName": "web-1",
        "domain": "example.com",
        "customerId": null,
        "status": "active",
        "defaultTtl": 3600,
        "soaEmail": "hostmaster@example.com",
        "serial": 2026111002,
        "appliedSerial": 2026111002,
        "appliedAt": "2026-11-10T09:12:44.000Z",
        "pending": false,
        "applying": false,
        "recordCount": 9,
        "delegation": null,
        "lastJobId": "d3c1b2a0-7e6f-4a5b-8c9d-0e1f2a3b4c5d",
        "lastError": null,
        "createdAt": "2026-11-10T09:12:30.000Z",
        "updatedAt": "2026-11-10T09:12:44.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "0f6c1d9e-…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | Missing `dns.read`, or a hosting customer. |
| 422 | `VALIDATION_ERROR` | A query parameter is invalid. |

## Create a zone

`POST /api/v1/dns/zones` — Permission: dns.manage — Token scope: manage

Adds a zone on a server whose DNS server is set up, with default records, and sends it to the server. The default records are an `NS` record for each name server, `A` (and `AAAA` with `ipv6`) records for `@`, `www` and each name server inside the domain, and with `mailRecords` a `mail` address record, an `MX` record (priority 10, `mail.<domain>`) and the SPF record `v=spf1 a mx ~all`.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string (UUID) | Yes | The server whose BIND serves the zone. |
| `domain` | string | Yes | The domain. A final dot is removed. |
| `ipv4` | string | No | Where the domain and `www` point. Defaults to the server's public IPv4 address. |
| `ipv6` | string or null | No | An IPv6 address to add `AAAA` records for. |
| `nameservers` | string[] | No | 1 to 4 name servers. Defaults to `ns1.<domain>` and `ns2.<domain>`. |
| `mailRecords` | boolean | No | Also add the `mail`, `MX` and SPF records. Default `true`. |
| `defaultTtl` | integer | No | 60 to 604800 seconds. Default 3600. |
| `soaEmail` | string | No | SOA contact. Default `hostmaster@<domain>`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "domain": "example.com" }'
```

**JavaScript**

```js
const { zone, job } = await panel.dns.createZone({
  serverId: '9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c',
  domain: 'example.com',
});
```

**Response** `202 Accepted`

The new zone (with `records` and `nameservers`) and the `DNS_ZONE_APPLY` job that sends it.

```json
{
  "success": true,
  "data": {
    "zone": {
      "id": "4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f",
      "domain": "example.com",
      "status": "creating",
      "serial": 2026111001,
      "appliedSerial": null,
      "pending": true,
      "applying": true,
      "recordCount": 9,
      "records": [
        { "id": "…", "name": "@", "fullName": "example.com", "type": "NS", "ttl": null, "value": "ns1.example.com", "priority": null, "weight": null, "port": null, "tag": null }
      ],
      "nameservers": [
        { "host": "ns1.example.com", "inZone": true, "addresses": ["203.0.113.10"] },
        { "host": "ns2.example.com", "inZone": true, "addresses": ["203.0.113.10"] }
      ]
    },
    "job": { "id": "d3c1b2a0-7e6f-4a5b-8c9d-0e1f2a3b4c5d", "type": "DNS_ZONE_APPLY", "status": "queued", "resource": { "type": "dns_zone", "id": "4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f" } }
  },
  "message": "Adding the zone to the server",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `SERVER_NOT_READY` | The server has no connected agent yet. |
| 409 | `AGENT_OUTDATED` | The server's agent is too old to serve DNS zones. |
| 409 | `DNS_NOT_SET_UP` | BIND is not set up on the server yet. |
| 422 | `VALIDATION_ERROR` | Invalid fields, the server does not exist, a zone for the domain already exists, the panel knows no public address for the server and none was given, or the default records would not load. |

## Get a zone

`GET /api/v1/dns/zones/:id` — Permission: dns.read — Token scope: read

Returns one zone with its `records` and `nameservers`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const zone = await panel.dns.zone('4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f');
```

**Response** `200 OK`: the [zone object](https://docs.vaultpanel.net/api-reference/dns#the-zone-object) with `records` and `nameservers`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |

## Update a zone

`PATCH /api/v1/dns/zones/:id` — Permission: dns.manage — Token scope: manage

Changes the zone's default TTL or SOA contact, raises the serial and sends the zone again. Send at least one field.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `defaultTtl` | integer | No | 60 to 604800 seconds. |
| `soaEmail` | string | No | SOA contact, such as `hostmaster@example.com`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "defaultTtl": 300 }'
```

**JavaScript**

```js
const { zone, job } = await panel.dns.updateZone(zoneId, { defaultTtl: 300 });
```

**Response** `202 Accepted`: `{ zone, job }`. `job` is `null` when an apply is already on its way: the change is sent right after it.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |
| 409 | `DNS_ZONE_DELETING` | The zone is being deleted. |
| 422 | `VALIDATION_ERROR` | No field given, or a field is invalid. |

## Delete a zone

`DELETE /api/v1/dns/zones/:id` — Permission: dns.manage — Token scope: manage

Marks the zone `deleting` and queues a `DNS_ZONE_REMOVE` job that removes it from BIND.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { zone, job } = await panel.dns.removeZone(zoneId);
```

**Response** `202 Accepted`: `{ zone, job }` with the zone in status `deleting`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |
| 409 | `DNS_ZONE_DELETING` | The zone is already being deleted (`details.jobId` when known). |

## Apply a zone again

`POST /api/v1/dns/zones/:id/apply` — Permission: dns.manage — Token scope: manage

Sends the zone to the server again, for example after a failed apply or to put back a zone file someone changed by hand. Clears the last error, and moves a `failed` zone back to `creating`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/apply \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { zone, job } = await panel.dns.apply(zoneId);
```

**Response** `202 Accepted`: `{ zone, job }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |
| 409 | `DNS_ZONE_DELETING` | The zone is being deleted. |
| 409 | `DNS_ZONE_BUSY` | An apply is running right now (`details.jobId`). |

## Check name servers in public DNS

`POST /api/v1/dns/zones/:id/check` — Permission: dns.read — Token scope: read

Asks public DNS which name servers the domain has and compares them with the zone's `@` NS records. The result is saved on the zone as `delegation`.

| `delegation.status` | Meaning |
| --- | --- |
| `ok` | Public DNS lists exactly the zone's name servers. |
| `partial` | Some, but not all, of the listed name servers are the zone's. |
| `elsewhere` | None of the listed name servers are the zone's. |
| `unresolved` | Public DNS has no name servers for the domain (not registered yet, or not published). |
| `error` | The lookup failed; try again in a minute. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/check \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { zone, expected } = await panel.dns.check(zoneId);
console.log(zone.delegation.status);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "zone": {
      "id": "4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f",
      "domain": "example.com",
      "delegation": {
        "status": "elsewhere",
        "nameservers": ["ns1.registrar-dns.net", "ns2.registrar-dns.net"],
        "detail": "Public DNS lists ns1.registrar-dns.net, ns2.registrar-dns.net. Set the domain's name servers to ns1.example.com, ns2.example.com at its registrar.",
        "checkedAt": "2026-11-10T09:30:00.000Z"
      }
    },
    "expected": ["ns1.example.com", "ns2.example.com"]
  },
  "message": "OK",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |

## Add a record

`POST /api/v1/dns/zones/:id/records` — Permission: dns.manage — Token scope: manage

Adds a record, raises the serial and sends the zone. Names may be relative (`www`) or full (`www.example.com`); host names may end with a dot. A zone holds up to 500 records.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Record name, up to 253 characters. `@` for the domain itself. |
| `type` | string | Yes | `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV` or `CAA`. |
| `value` | string | Yes | Address, host name or text (up to 2048 characters). |
| `ttl` | integer or null | No | 60 to 604800 seconds; `null` uses the zone's default. |
| `priority` | integer or null | No | 0 to 65535. `MX` and `SRV`. |
| `weight` | integer or null | No | 0 to 65535. `SRV`. |
| `port` | integer or null | No | 0 to 65535. `SRV`. |
| `tag` | string or null | No | `CAA`: `issue` (default), `issuewild` or `iodef`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/records \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "blog", "type": "CNAME", "value": "example.com" }'
```

**JavaScript**

```js
const { record, zone, job } = await panel.dns.addRecord(zoneId, {
  name: 'blog',
  type: 'CNAME',
  value: 'example.com',
});
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "record": { "id": "7a8b9c0d-…", "name": "blog", "fullName": "blog.example.com", "type": "CNAME", "ttl": null, "value": "example.com", "priority": null, "weight": null, "port": null, "tag": null },
    "zone": { "id": "4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f", "serial": 2026111003, "pending": true },
    "job": { "id": "…", "type": "DNS_ZONE_APPLY", "status": "queued" }
  },
  "message": "Record added",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone with this id. |
| 409 | `DNS_ZONE_DELETING` | The zone is being deleted. |
| 422 | `VALIDATION_ERROR` | The record is invalid, or the zone with it would not load (for example a `CNAME` next to other records of the same name, or more than 500 records). |

## Update a record

`PATCH /api/v1/dns/zones/:id/records/:recordId` — Permission: dns.manage — Token scope: manage

Changes any of the record's fields (the same fields as [Add a record](https://docs.vaultpanel.net/api-reference/dns#add-a-record), all optional; send at least one). The result is checked with the rest of the zone before it is saved.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/records/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": 300 }'
```

**JavaScript**

```js
const { record } = await panel.dns.updateRecord(zoneId, recordId, { ttl: 300 });
```

**Response** `202 Accepted`: `{ record, zone, job }`, message `Record saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone, or no record with this id in the zone. |
| 409 | `DNS_ZONE_DELETING` | The zone is being deleted. |
| 422 | `VALIDATION_ERROR` | No field given, or the changed record or zone is invalid. |

## Delete a record

`DELETE /api/v1/dns/zones/:id/records/:recordId` — Permission: dns.manage — Token scope: manage

Deletes the record, raises the serial and sends the zone. Refused when the zone would not load without it.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/records/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { zone, job } = await panel.dns.removeRecord(zoneId, recordId);
```

**Response** `202 Accepted`: `{ zone, job }`, message `Record deleted`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No zone, or no record with this id in the zone. |
| 409 | `DNS_ZONE_DELETING` | The zone is being deleted. |
| 422 | `VALIDATION_ERROR` | The zone would be invalid without the record. |

## Set customer name servers

`PUT /api/v1/dns/servers/:id/customers` — Permission: dns.manage — Token scope: manage

Sets what hosting customers whose account is on this server are told about DNS: the name servers to enter at their registrar, and whether each new customer domain (a registered domain such as `example.com`, not a subdomain) automatically gets a zone on this server. Zones added this way are removed with the account.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `nameservers` | string[] | Yes | Up to 4 host names. An empty list clears them. |
| `autoZones` | boolean | Yes | Add a zone for each new customer domain. Needs BIND set up on the server. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/servers/9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c/customers \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nameservers": ["ns1.example.net", "ns2.example.net"], "autoZones": true }'
```

**JavaScript**

```js
await panel.request('PUT', `/dns/servers/${serverId}/customers`, {
  body: { nameservers: ['ns1.example.net', 'ns2.example.net'], autoZones: true },
});
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": { "nameservers": ["ns1.example.net", "ns2.example.net"], "autoZones": true },
  "message": "Saved",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No server with this id. |
| 409 | `SERVER_NOT_READY`, `AGENT_OUTDATED`, `DNS_NOT_SET_UP` | `autoZones` is `true` but the server cannot serve zones. |
| 422 | `VALIDATION_ERROR` | More than 4 name servers, or an invalid host name. |

## List DNS providers

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

Returns every DNS provider account with `certificates`: how many active certificates of live websites renew through it. Secrets are never returned.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.request('GET', '/dns/providers');
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
        "name": "Cloudflare (main)",
        "type": "cloudflare",
        "typeLabel": "Cloudflare",
        "username": null,
        "certificates": 2,
        "createdAt": "2026-10-31T08:00:00.000Z",
        "updatedAt": "2026-10-31T08:00:00.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Add a DNS provider

`POST /api/v1/dns/providers` — Permission: dns.manage — Token scope: manage

Saves a provider account. The secret is stored encrypted and sent to a server only inside the job that issues a certificate. Using a provider needs agent 0.38.0 or newer on the server that issues the certificate.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Up to 60 letters, digits, spaces and `. _ ( ) -`, starting with a letter or digit. Unique. |
| `type` | string | Yes | `cloudflare` or `namecheap`. |
| `username` | string | Namecheap | Your Namecheap user name (the API user). Ignored for Cloudflare. |
| `secret` | string | Yes | A Cloudflare API token with the **Zone > DNS > Edit** permission, or a Namecheap API key. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/providers \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cloudflare (main)", "type": "cloudflare", "secret": "'"$CLOUDFLARE_API_TOKEN"'" }'
```

**JavaScript**

```js
const { provider } = await panel.request('POST', '/dns/providers', {
  body: { name: 'Cloudflare (main)', type: 'cloudflare', secret: process.env.CLOUDFLARE_API_TOKEN },
});
```

**Response** `201 Created`: `{ provider }`, message `DNS provider added`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 422 | `VALIDATION_ERROR` | A missing or malformed secret, a missing Namecheap user name, or a name another provider has. |

## Get a DNS provider

`GET /api/v1/dns/providers/:id` — Permission: dns.read — Token scope: read

Returns `{ provider }`, the same object as in the list.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/providers/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { provider } = await panel.request('GET', `/dns/providers/${providerId}`);
```

**Response** `200 OK`: `{ provider }`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No provider with this id. |

## Update a DNS provider

`PUT /api/v1/dns/providers/:id` — Permission: dns.manage — Token scope: manage

Renames the provider or replaces its credentials. Send the same fields as [Add a DNS provider](https://docs.vaultpanel.net/api-reference/dns#add-a-dns-provider): `type` must stay the same, and a blank or missing `secret` keeps the saved one. Servers keep the copy they received until a certificate is issued again.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/providers/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f \
  -X PUT \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cloudflare", "type": "cloudflare" }'
```

**JavaScript**

```js
await panel.request('PUT', `/dns/providers/${providerId}`, {
  body: { name: 'Cloudflare', type: 'cloudflare' },
});
```

**Response** `200 OK`: `{ provider }`, message `DNS provider saved`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No provider with this id. |
| 422 | `VALIDATION_ERROR` | The type changed, a field is invalid, or the name is taken. |

## Delete a DNS provider

`DELETE /api/v1/dns/providers/:id` — Permission: dns.manage — Token scope: manage

Deletes the provider. Refused while active certificates renew through it: issue them again another way, or turn HTTPS off on those websites, first.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/dns/providers/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.request('DELETE', `/dns/providers/${providerId}`);
```

**Response** `200 OK`: `data` is `null`, message `DNS provider removed`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No provider with this id. |
| 409 | `DNS_PROVIDER_IN_USE` | Certificates renew through it (`details.certificates`). |
