Zones

Manipulating zones is the primary use of the API.

Zone Endpoints

GET /servers/{server_id}/zones

List all Zones in a server

Parameters:
  • server_id (string) – The id of the server to retrieve
Status Codes:
  • 200 OK – An array of Zones Returns: array of Zone objects
POST /servers/{server_id}/zones

Creates a new domain, returns the Zone on creation.

Parameters:
  • server_id (string) – The id of the server to retrieve
Query Parameters:
 
  • rrsets (boolean) – “true” (default) or “false”, whether to include the “rrsets” in the response Zone object.
Status Codes:
GET /servers/{server_id}/zones/{zone_id}

zone managed by a server

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
DELETE /servers/{server_id}/zones/{zone_id}

Deletes this zone, all attached metadata and rrsets.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
PATCH /servers/{server_id}/zones/{zone_id}

Modifies present RRsets and comments. Returns 204 No Content on success.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) –
Status Codes:
PUT /servers/{server_id}/zones/{zone_id}

Modifies basic zone data (metadata).

Allowed fields in client body: all except id, url and name. Returns 204 No Content on success.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) –
Status Codes:
PUT /servers/{server_id}/zones/{zone_id}/axfr-retrieve

Send a DNS NOTIFY to all slaves.

Fails when zone kind is not Master or Slave, or master and slave are disabled in the configuration. Only works for Slave if renotify is on. Clients MUST NOT send a body.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
PUT /servers/{server_id}/zones/{zone_id}/notify

Send a DNS NOTIFY to all slaves.

Fails when zone kind is not Master or Slave, or master and slave are disabled in the configuration. Only works for Slave if renotify is on. Clients MUST NOT send a body.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
GET /servers/{server_id}/zones/{zone_id}/export

Returns the zone in AXFR format.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
  • 200 OK – OK Returns: string
GET /servers/{server_id}/zones/{zone_id}/check

Verify zone contents/configuration.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
  • 200 OK – OK Returns: string
PUT /servers/{server_id}/zones/{zone_id}/rectify

Rectify the zone data.

This does not take into account the API-RECTIFY metadata. Fails on slave zones and zones that do not have DNSSEC.

Parameters:
  • server_id (string) – The id of the server to retrieve
  • zone_id (string) – The id of the zone to retrieve
Status Codes:
  • 200 OK – OK Returns: string

Objects

A Zone object represents an authoritative DNS Zone.

A Resource Record Set (below as “RRset”) are all records for a given name and type.

Comments are per-RRset.

Zone

This represents an authoritative DNS Zone.

Object Properties:
 
  • id (string) – Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs.
  • name (string) – Name of the zone (e.g. “example.com.”) MUST have a trailing dot
  • type (string) – Set to “Zone”
  • url (string) – API endpoint for this zone
  • kind (string) – Zone kind, one of “Native”, “Master”, “Slave”
  • rrsets ([RRSet]) – RRSets in this zone
  • serial (integer) – The SOA serial number
  • notified_serial (integer) – The SOA serial notifications have been sent out for
  • masters ([string]) – List of IP addresses configured as a master for this zone (“Slave” type zones only)
  • dnssec (boolean) – Whether or not this zone is DNSSEC signed (inferred from presigned being true XOR presence of at least one cryptokey with active being true)
  • nsec3param (string) – The NSEC3PARAM record
  • nsec3narrow (boolean) – Whether or not the zone uses NSEC3 narrow
  • presigned (boolean) – Whether or not the zone is pre-signed
  • soa_edit (string) – The SOA-EDIT metadata item
  • soa_edit_api (string) – The SOA-EDIT-API metadata item
  • api_rectify (boolean) – Whether or not the zone will be rectified on data changes via the API
  • zone (string) – MAY contain a BIND-style zone file when creating a zone
  • account (string) – MAY be set. Its value is defined by local policy
  • nameservers ([string]) – MAY be sent in client bodies during creation, and MUST NOT be sent by the server. Simple list of strings of nameserver names, including the trailing dot. Not required for slave zones.
RRSet

This represents a Resource Record Set (all records with the same name and type).

Object Properties:
 
  • name (string) – Name for record set (e.g. “www.powerdns.com.”)
  • type (string) – Type of this record (e.g. “A”, “PTR”, “MX”)
  • ttl (integer) – DNS TTL of the records, in seconds. MUST NOT be included when changetype is set to “DELETE”.
  • changetype (string) – MUST be added when updating the RRSet. Must be REPLACE or DELETE. With DELETE, all existing RRs matching name and type will be deleted, including all comments. With REPLACE: when records is present, all existing RRs matching name and type will be deleted, and then new records given in records will be created. If no records are left, any existing comments will be deleted as well. When comments is present, all existing comments for the RRs matching name and type will be deleted, and then new comments given in comments will be created.
  • records ([Record]) – All records in this RRSet. When updating Records, this is the list of new records (replacing the old ones). Must be empty when changetype is set to DELETE. An empty list results in deletion of all records (and comments).
  • comments ([Comment]) – List of Comment. Must be empty when changetype is set to DELETE. An empty list results in deletion of all comments. modified_at is optional and defaults to the current server time.
Record

The RREntry object represents a single record.

Object Properties:
 
  • content (string) – The content of this record
  • disabled (boolean) – Whether or not this record is disabled
  • set-ptr (boolean) – If set to true, the server will find the matching reverse zone and create a PTR there. Existing PTR records are replaced. If no matching reverse Zone, an error is thrown. Only valid in client bodies, only valid for A and AAAA types. Not returned by the server.
Comment

A comment about an RRSet.

Object Properties:
 
  • content (string) – The actual comment
  • account (string) – Name of an account that added the comment
  • modifided_at (integer) – Timestamp of the last change to the comment

Note

Switching dnssec to true (from false) sets up DNSSEC signing based on the other flags, this includes running the equivalent of secure-zone and rectify-zone (if api_rectify is set to true). This also applies to newly created zones. If presigned is true, no DNSSEC changes will be made to the zone or cryptokeys.

Note

notified_serial, serial MUST NOT be sent in client bodies.

Changes made through the Zones API will always yield valid zone data, as the API will reject records with wrong data.

DNSSEC-enabled zones should be rectified after changing the zone data. This can be done by the API automatically after a change when the API-RECTIFY metadata is set. When creating or updating a zone, the “api_rectify” field of the ZOne can be set to true to enable this behaviour.

Backends might implement additional features (by coincidence or not). These things are not supported through the API.

When creating a slave zone, it is recommended to not set any of nameservers, rrsets or zone.