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. For concepts and the panel workflow, see DNS zones and DNS providers.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/dns/zones | List zones |
| POST | /api/v1/dns/zones | Create a zone |
| GET | /api/v1/dns/zones/:id | Get a zone |
| PATCH | /api/v1/dns/zones/:id | Update a zone |
| DELETE | /api/v1/dns/zones/:id | Delete a zone |
| POST | /api/v1/dns/zones/:id/apply | Apply a zone again |
| POST | /api/v1/dns/zones/:id/check | Check name servers in public DNS |
| POST | /api/v1/dns/zones/:id/records | Add a record |
| PATCH | /api/v1/dns/zones/:id/records/:recordId | Update a record |
| DELETE | /api/v1/dns/zones/:id/records/:recordId | Delete a record |
| PUT | /api/v1/dns/servers/:id/customers | Set customer name servers |
| GET | /api/v1/dns/providers | List DNS providers |
| POST | /api/v1/dns/providers | Add a DNS provider |
| GET | /api/v1/dns/providers/:id | Get a DNS provider |
| PUT | /api/v1/dns/providers/:id | Update a DNS provider |
| DELETE | /api/v1/dns/providers/:id | 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. |
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: { 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
/api/v1/dns/zonesReturns 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 "https://panel.example.com/api/v1/dns/zones?search=example" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items, pagination } = await panel.dns.zones({ search: 'example' });Response 200 OK
{
"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
/api/v1/dns/zonesAdds 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 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" }'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.
{
"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
/api/v1/dns/zones/:idReturns one zone with its records and nameservers.
Example request
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const zone = await panel.dns.zone('4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f');Response 200 OK: the zone object with records and nameservers.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No zone with this id. |
Update a zone
/api/v1/dns/zones/:idChanges 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 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 }'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
/api/v1/dns/zones/:idMarks the zone deleting and queues a DNS_ZONE_REMOVE job that removes it from BIND.
Example request
curl https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/dns/zones/:id/applySends 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 https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/apply \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/dns/zones/:id/checkAsks 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 https://panel.example.com/api/v1/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/check \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { zone, expected } = await panel.dns.check(zoneId);
console.log(zone.delegation.status);Response 200 OK
{
"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
/api/v1/dns/zones/:id/recordsAdds 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 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" }'const { record, zone, job } = await panel.dns.addRecord(zoneId, {
name: 'blog',
type: 'CNAME',
value: 'example.com',
});Response 202 Accepted
{
"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
/api/v1/dns/zones/:id/records/:recordIdChanges any of the record's fields (the same fields as 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 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 }'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
/api/v1/dns/zones/:id/records/:recordIdDeletes the record, raises the serial and sends the zone. Refused when the zone would not load without it.
Example request
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"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
/api/v1/dns/servers/:id/customersSets 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 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 }'await panel.request('PUT', `/dns/servers/${serverId}/customers`, {
body: { nameservers: ['ns1.example.net', 'ns2.example.net'], autoZones: true },
});Response 200 OK
{
"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
/api/v1/dns/providersReturns every DNS provider account with certificates: how many active certificates of live websites renew through it. Secrets are never returned.
Example request
curl https://panel.example.com/api/v1/dns/providers \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.request('GET', '/dns/providers');Response 200 OK
{
"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
/api/v1/dns/providersSaves 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 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"'" }'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
/api/v1/dns/providers/:idReturns { provider }, the same object as in the list.
Example request
curl https://panel.example.com/api/v1/dns/providers/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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
/api/v1/dns/providers/:idRenames the provider or replaces its credentials. Send the same fields as 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 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" }'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
/api/v1/dns/providers/:idDeletes 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 https://panel.example.com/api/v1/dns/providers/2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"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). |
Containers
API reference for Docker containers - deploying, changing, redeploying and removing containers, any container or image on a server, and Docker itself.
API reference for email hosting on your servers with Postfix, Dovecot and OpenDKIM - mail servers, email domains, mailboxes and forwarders.