Skip to main content
Zone endpoints work with an API token or a signed-in session. Paths take numeric ids: a division id for listing and creating, a zone id for the rest.

​
Endpoints

Records have their own endpoints; see Records.

​
Create a zone

POST /api/divisions/{id}/zones
​
string
required
The zone name, e.g. example.com.
​
integer
TTL in seconds for records created without one. Defaults to 300.
A token limited to some zones can’t create new zones.

​
Change a zone

PATCH /api/zones/{id}. Every field is optional; send only what changes.
​
boolean
Turn the zone on or off. See Turning a zone off.
​
integer
TTL for records created without one.
​
boolean
Forward names the zone doesn’t have to the upstreams. See Forwarding names a zone doesn’t have.

​
Turning a zone off

A disabled zone is kept, but:
  • it is not answered,
  • it is not sent in zone transfers (AXFR/IXFR),
  • it is not DNSSEC-signed,
  • it leaves the catalog zone, so DNZ secondaries drop it until it is turned on again.
Turning a local zone on or off bumps its SOA serial. Records can be turned off one by one too; see Records.

​
Forwarding names a zone doesn’t have

{"forward_missing": true} is the default for local zones. A query the zone has no answer for then goes through the normal path (filtering, forwarding rules, cache, upstreams) instead of getting NXDOMAIN, or NODATA when the name exists without that type. This lets a local zone override a few names of a public domain. What counts as having an answer:
  • a record of the type, or a CNAME, chased as usual (the answer stays local wherever the chase ends);
  • a wildcard match;
  • the apex SOA and NS.
Views are respected: a name a client’s view adds is answered for that client. Signed queries (update clients looking up a name’s zone, secondaries) always get this server’s answer.
forward_missing can’t be turned on for a DNSSEC-signed zone (400): its denial proofs say missing names don’t exist. Turning DNSSEC on turns it off. Secondary zones never forward.
Changing forward_missing doesn’t bump the serial.

​
Export a zone

GET /api/zones/{id}/export returns the zone as a BIND zone file.

​
Refresh a secondary zone

POST /api/zones/{id}/refresh makes a secondary zone check its primary for a new serial now.
​
boolean
true transfers the whole zone even if the serial is unchanged.

​
Query log

GET /api/divisions/{id}/logs returns the query log of the division’s zones, newest first. It needs logs.read.
​
string
Only queries whose name or client address contains this text.
​
string
Only queries from exactly this client address.
​
integer
default:"100"
How many entries to return, from 1 to 1000.
See Query logs for what each entry means.

​
Token info

GET /api/token tells you what the calling token may do. It needs no permission, but it must be called with an API token.
​
integer
The token’s id.
​
string
The token’s name.
​
object
The division it belongs to: id and name.
​
string[]
Its permissions, e.g. ["zones.read", "records.write"].
​
object[]
The zones it can reach, each with id and name.