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.

Last updated

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.

MethodPathDescription
GET/api/v1/dns/zonesList zones
POST/api/v1/dns/zonesCreate a zone
GET/api/v1/dns/zones/:idGet a zone
PATCH/api/v1/dns/zones/:idUpdate a zone
DELETE/api/v1/dns/zones/:idDelete a zone
POST/api/v1/dns/zones/:id/applyApply a zone again
POST/api/v1/dns/zones/:id/checkCheck name servers in public DNS
POST/api/v1/dns/zones/:id/recordsAdd a record
PATCH/api/v1/dns/zones/:id/records/:recordIdUpdate a record
DELETE/api/v1/dns/zones/:id/records/:recordIdDelete a record
PUT/api/v1/dns/servers/:id/customersSet customer name servers
GET/api/v1/dns/providersList DNS providers
POST/api/v1/dns/providersAdd a DNS provider
GET/api/v1/dns/providers/:idGet a DNS provider
PUT/api/v1/dns/providers/:idUpdate a DNS provider
DELETE/api/v1/dns/providers/:idDelete a DNS provider

The zone object

FieldTypeDescription
idstring (UUID)Zone id.
serverId, serverNamestringThe server whose BIND serves the zone.
domainstringThe zone's domain, such as example.com.
customerIdstring or nullThe hosting account the zone was added for automatically, if any.
statusstringcreating (first apply running), active, failed (first apply failed) or deleting.
defaultTtlintegerDefault TTL in seconds.
soaEmailstringThe SOA contact address (hostmaster@<domain> unless set).
serial, appliedSerialintegerThe zone's serial, and the serial the server confirmed.
appliedAtstring or nullWhen the server last confirmed the zone.
pendingbooleantrue while the server does not have the latest changes yet.
applyingbooleantrue while a DNS_ZONE_APPLY job is queued or running.
recordCountintegerNumber of records.
recordsarrayOnly on single-zone responses: every record.
nameserversarrayOnly on single-zone responses: the zone's @ NS records as { host, inZone, addresses }, what to enter at the registrar.
delegationobject or nullThe last name server check: { status, nameservers, detail, checkedAt }.
lastJobIdstring or nullThe last job sent for the zone.
lastErrorobject or null{ code, message } of the last failed job.
createdAt, updatedAtstringISO 8601 timestamps.

The record object

FieldTypeDescription
idstring (UUID)Record id.
namestringName relative to the zone: @ for the domain itself, www, mail…
fullNamestringThe full name, such as www.example.com.
typestringA, AAAA, CNAME, MX, TXT, NS, SRV or CAA.
ttlinteger or nullTTL in seconds, or null for the zone's default.
valuestringAddress, host name or text.
priorityinteger or nullMX and SRV only.
weight, portinteger or nullSRV only.
tagstring or nullCAA only: issue, issuewild or iodef.

List zones

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

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

Query parameters

NameTypeRequiredDescription
searchstringNoPart of the domain, up to 100 characters.
serverIdstring (UUID)NoOnly zones on this server.
page, pageSizeintegerNoPage number from 1, and 1 to 100 items per page (default 25).
sortstringNodomain (default) or createdAt.
orderstringNoasc (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

StatusCodeWhen
403FORBIDDENMissing dns.read, or a hosting customer.
422VALIDATION_ERRORA query parameter is invalid.

Create a zone

POST/api/v1/dns/zones
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
serverIdstring (UUID)YesThe server whose BIND serves the zone.
domainstringYesThe domain. A final dot is removed.
ipv4stringNoWhere the domain and www point. Defaults to the server's public IPv4 address.
ipv6string or nullNoAn IPv6 address to add AAAA records for.
nameserversstring[]No1 to 4 name servers. Defaults to ns1.<domain> and ns2.<domain>.
mailRecordsbooleanNoAlso add the mail, MX and SPF records. Default true.
defaultTtlintegerNo60 to 604800 seconds. Default 3600.
soaEmailstringNoSOA 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

StatusCodeWhen
409SERVER_NOT_READYThe server has no connected agent yet.
409AGENT_OUTDATEDThe server's agent is too old to serve DNS zones.
409DNS_NOT_SET_UPBIND is not set up on the server yet.
422VALIDATION_ERRORInvalid 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
Auth
Session cookie (+ CSRF token) or API token
Permission
dns.read
Token scope
read

Returns 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.

Update a zone

PATCH/api/v1/dns/zones/:id
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
defaultTtlintegerNo60 to 604800 seconds.
soaEmailstringNoSOA 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.
409DNS_ZONE_DELETINGThe zone is being deleted.
422VALIDATION_ERRORNo field given, or a field is invalid.

Delete a zone

DELETE/api/v1/dns/zones/:id
Auth
Session cookie (+ CSRF token) or API token
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 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.
409DNS_ZONE_DELETINGThe zone is already being deleted (details.jobId when known).

Apply a zone again

POST/api/v1/dns/zones/:id/apply
Auth
Session cookie (+ CSRF token) or API token
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 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.
409DNS_ZONE_DELETINGThe zone is being deleted.
409DNS_ZONE_BUSYAn apply is running right now (details.jobId).

Check name servers in public DNS

POST/api/v1/dns/zones/:id/check
Auth
Session cookie (+ CSRF token) or API token
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.statusMeaning
okPublic DNS lists exactly the zone's name servers.
partialSome, but not all, of the listed name servers are the zone's.
elsewhereNone of the listed name servers are the zone's.
unresolvedPublic DNS has no name servers for the domain (not registered yet, or not published).
errorThe 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.

Add a record

POST/api/v1/dns/zones/:id/records
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
namestringYesRecord name, up to 253 characters. @ for the domain itself.
typestringYesA, AAAA, CNAME, MX, TXT, NS, SRV or CAA.
valuestringYesAddress, host name or text (up to 2048 characters).
ttlinteger or nullNo60 to 604800 seconds; null uses the zone's default.
priorityinteger or nullNo0 to 65535. MX and SRV.
weightinteger or nullNo0 to 65535. SRV.
portinteger or nullNo0 to 65535. SRV.
tagstring or nullNoCAA: 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

StatusCodeWhen
404NOT_FOUNDNo zone with this id.
409DNS_ZONE_DELETINGThe zone is being deleted.
422VALIDATION_ERRORThe 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
Auth
Session cookie (+ CSRF token) or API token
Permission
dns.manage
Token scope
manage

Changes 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

StatusCodeWhen
404NOT_FOUNDNo zone, or no record with this id in the zone.
409DNS_ZONE_DELETINGThe zone is being deleted.
422VALIDATION_ERRORNo field given, or the changed record or zone is invalid.

Delete a record

DELETE/api/v1/dns/zones/:id/records/:recordId
Auth
Session cookie (+ CSRF token) or API token
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 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

StatusCodeWhen
404NOT_FOUNDNo zone, or no record with this id in the zone.
409DNS_ZONE_DELETINGThe zone is being deleted.
422VALIDATION_ERRORThe zone would be invalid without the record.

Set customer name servers

PUT/api/v1/dns/servers/:id/customers
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
nameserversstring[]YesUp to 4 host names. An empty list clears them.
autoZonesbooleanYesAdd 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

StatusCodeWhen
404NOT_FOUNDNo server with this id.
409SERVER_NOT_READY, AGENT_OUTDATED, DNS_NOT_SET_UPautoZones is true but the server cannot serve zones.
422VALIDATION_ERRORMore than 4 name servers, or an invalid host name.

List DNS providers

GET/api/v1/dns/providers
Auth
Session cookie (+ CSRF token) or API token
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 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

POST/api/v1/dns/providers
Auth
Session cookie (+ CSRF token) or API token
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

FieldTypeRequiredDescription
namestringYesUp to 60 letters, digits, spaces and . _ ( ) -, starting with a letter or digit. Unique.
typestringYescloudflare or namecheap.
usernamestringNamecheapYour Namecheap user name (the API user). Ignored for Cloudflare.
secretstringYesA 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

StatusCodeWhen
422VALIDATION_ERRORA 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
Auth
Session cookie (+ CSRF token) or API token
Permission
dns.read
Token scope
read

Returns { 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

StatusCodeWhen
404NOT_FOUNDNo provider with this id.

Update a DNS provider

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

Renames 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

StatusCodeWhen
404NOT_FOUNDNo provider with this id.
422VALIDATION_ERRORThe type changed, a field is invalid, or the name is taken.

Delete a DNS provider

DELETE/api/v1/dns/providers/:id
Auth
Session cookie (+ CSRF token) or API token
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 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

StatusCodeWhen
404NOT_FOUNDNo provider with this id.
409DNS_PROVIDER_IN_USECertificates renew through it (details.certificates).