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

Query Parameters:

  • zone (string) – When set to the name of a zone, only this zone is returned. If no zone with that name exists, the response is an empty array. This can e.g. be used to check if a zone exists in the database without having to guess/encode the zone’s id or to check if a zone exists.

  • dnssec (boolean) – “true” (default) or “false”, whether to include the “dnssec” and “edited_serial” fields in the Zone objects. Setting this to ”false” will make the query a lot faster.

Example request:

GET /servers/{server_id}/zones HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    An array of Zones

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "string",
        "name": "string",
        "type": "string",
        "url": "string",
        "kind": "Native",
        "rrsets": [
            {
                "name": "string",
                "type": "string",
                "ttl": 1,
                "changetype": "string",
                "records": [
                    {
                        "content": "string",
                        "disabled": true
                    }
                ],
                "comments": [
                    {
                        "content": "string",
                        "account": "string",
                        "modified_at": 1
                    }
                ]
            }
        ],
        "serial": 1,
        "notified_serial": 1,
        "edited_serial": 1,
        "masters": [
            "string"
        ],
        "dnssec": true,
        "nsec3param": "string",
        "nsec3narrow": true,
        "presigned": true,
        "soa_edit": "string",
        "soa_edit_api": "string",
        "api_rectify": true,
        "zone": "string",
        "catalog": "string",
        "account": "string",
        "nameservers": [
            "string"
        ],
        "master_tsig_key_ids": [
            "string"
        ],
        "slave_tsig_key_ids": [
            "string"
        ],
        "last_check": 1
    }
]

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

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.

Example request:

POST /servers/{server_id}/zones HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": "string",
    "name": "string",
    "type": "string",
    "url": "string",
    "kind": "Native",
    "rrsets": [
        {
            "name": "string",
            "type": "string",
            "ttl": 1,
            "changetype": "string",
            "records": [
                {
                    "content": "string",
                    "disabled": true
                }
            ],
            "comments": [
                {
                    "content": "string",
                    "account": "string",
                    "modified_at": 1
                }
            ]
        }
    ],
    "serial": 1,
    "notified_serial": 1,
    "edited_serial": 1,
    "masters": [
        "string"
    ],
    "dnssec": true,
    "nsec3param": "string",
    "nsec3narrow": true,
    "presigned": true,
    "soa_edit": "string",
    "soa_edit_api": "string",
    "api_rectify": true,
    "zone": "string",
    "catalog": "string",
    "account": "string",
    "nameservers": [
        "string"
    ],
    "master_tsig_key_ids": [
        "string"
    ],
    "slave_tsig_key_ids": [
        "string"
    ],
    "last_check": 1
}
Status Codes:

  • 201 Created –

    A zone

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "string",
    "name": "string",
    "type": "string",
    "url": "string",
    "kind": "Native",
    "rrsets": [
        {
            "name": "string",
            "type": "string",
            "ttl": 1,
            "changetype": "string",
            "records": [
                {
                    "content": "string",
                    "disabled": true
                }
            ],
            "comments": [
                {
                    "content": "string",
                    "account": "string",
                    "modified_at": 1
                }
            ]
        }
    ],
    "serial": 1,
    "notified_serial": 1,
    "edited_serial": 1,
    "masters": [
        "string"
    ],
    "dnssec": true,
    "nsec3param": "string",
    "nsec3narrow": true,
    "presigned": true,
    "soa_edit": "string",
    "soa_edit_api": "string",
    "api_rectify": true,
    "zone": "string",
    "catalog": "string",
    "account": "string",
    "nameservers": [
        "string"
    ],
    "master_tsig_key_ids": [
        "string"
    ],
    "slave_tsig_key_ids": [
        "string"
    ],
    "last_check": 1
}

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

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

Query Parameters:

  • rrsets (boolean) – “true” (default) or “false”, whether to include the “rrsets” in the response Zone object.

  • rrset_name (string) – Limit output to RRsets for this name.

  • rrset_type (string) – Limit output to the RRset of this type. Can only be used together with rrset_name.

  • include_disabled (boolean) – “true” (default) or “false”, whether to include disabled RRsets in the response.

Example request:

GET /servers/{server_id}/zones/{zone_id} HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    A Zone

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "string",
    "name": "string",
    "type": "string",
    "url": "string",
    "kind": "Native",
    "rrsets": [
        {
            "name": "string",
            "type": "string",
            "ttl": 1,
            "changetype": "string",
            "records": [
                {
                    "content": "string",
                    "disabled": true
                }
            ],
            "comments": [
                {
                    "content": "string",
                    "account": "string",
                    "modified_at": 1
                }
            ]
        }
    ],
    "serial": 1,
    "notified_serial": 1,
    "edited_serial": 1,
    "masters": [
        "string"
    ],
    "dnssec": true,
    "nsec3param": "string",
    "nsec3narrow": true,
    "presigned": true,
    "soa_edit": "string",
    "soa_edit_api": "string",
    "api_rectify": true,
    "zone": "string",
    "catalog": "string",
    "account": "string",
    "nameservers": [
        "string"
    ],
    "master_tsig_key_ids": [
        "string"
    ],
    "slave_tsig_key_ids": [
        "string"
    ],
    "last_check": 1
}

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

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:

  • 204 No Content – Returns 204 No Content on success.

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

PATCH /servers/{server_id}/zones/{zone_id}

Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success.

Parameters:

  • server_id (string) – The id of the server to retrieve

  • zone_id (string) – The id of the zone to retrieve

Example request:

PATCH /servers/{server_id}/zones/{zone_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": "string",
    "name": "string",
    "type": "string",
    "url": "string",
    "kind": "Native",
    "rrsets": [
        {
            "name": "string",
            "type": "string",
            "ttl": 1,
            "changetype": "string",
            "records": [
                {
                    "content": "string",
                    "disabled": true
                }
            ],
            "comments": [
                {
                    "content": "string",
                    "account": "string",
                    "modified_at": 1
                }
            ]
        }
    ],
    "serial": 1,
    "notified_serial": 1,
    "edited_serial": 1,
    "masters": [
        "string"
    ],
    "dnssec": true,
    "nsec3param": "string",
    "nsec3narrow": true,
    "presigned": true,
    "soa_edit": "string",
    "soa_edit_api": "string",
    "api_rectify": true,
    "zone": "string",
    "catalog": "string",
    "account": "string",
    "nameservers": [
        "string"
    ],
    "master_tsig_key_ids": [
        "string"
    ],
    "slave_tsig_key_ids": [
        "string"
    ],
    "last_check": 1
}
Status Codes:

  • 204 No Content – Returns 204 No Content on success.

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

PUT /servers/{server_id}/zones/{zone_id}

Modifies basic zone data.

The only fields in the zone structure which can be modified are: kind, masters, catalog, account, soa_edit, soa_edit_api, api_rectify, dnssec, and nsec3param. All other fields are ignored.

Parameters:

  • server_id (string) – The id of the server to retrieve

  • zone_id (string) – The id of the zone to retrieve

Example request:

PUT /servers/{server_id}/zones/{zone_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": "string",
    "name": "string",
    "type": "string",
    "url": "string",
    "kind": "Native",
    "rrsets": [
        {
            "name": "string",
            "type": "string",
            "ttl": 1,
            "changetype": "string",
            "records": [
                {
                    "content": "string",
                    "disabled": true
                }
            ],
            "comments": [
                {
                    "content": "string",
                    "account": "string",
                    "modified_at": 1
                }
            ]
        }
    ],
    "serial": 1,
    "notified_serial": 1,
    "edited_serial": 1,
    "masters": [
        "string"
    ],
    "dnssec": true,
    "nsec3param": "string",
    "nsec3narrow": true,
    "presigned": true,
    "soa_edit": "string",
    "soa_edit_api": "string",
    "api_rectify": true,
    "zone": "string",
    "catalog": "string",
    "account": "string",
    "nameservers": [
        "string"
    ],
    "master_tsig_key_ids": [
        "string"
    ],
    "slave_tsig_key_ids": [
        "string"
    ],
    "last_check": 1
}
Status Codes:

  • 204 No Content – Returns 204 No Content on success.

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

PUT /servers/{server_id}/zones/{zone_id}/axfr-retrieve

Retrieve slave zone from its master.

Fails when zone kind is not Slave, or slave is disabled in the configuration. 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:

  • 200 OK – OK

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

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:

  • 200 OK – OK

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

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

Example request:

GET /servers/{server_id}/zones/{zone_id}/export HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    OK

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

string

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "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

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

string

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

Objects

A Zone object represents an authoritative DNS Zone.

json Zone : object

Zone

This represents an authoritative DNS Zone.

Optional members:
account : string

MAY be set. Its value is defined by local policy

api_rectify : boolean

Whether or not the zone will be rectified on data changes via the API

catalog : string

The catalog this zone is a member of

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)

edited_serial : integer

The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings

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.

kind : "Native" | "Master" | "Slave" | "Producer" | "Consumer"

Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”

last_check : integer
master_tsig_key_ids : array of string

The id of the TSIG keys used for master operation in this zone

masters : array of string

List of IP addresses configured as a master for this zone (“Slave” type zones only)

name : string

Name of the zone (e.g. “example.com.”) MUST have a trailing dot

nameservers : array of 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.

notified_serial : integer

The SOA serial notifications have been sent out for

nsec3narrow : boolean

Whether or not the zone uses NSEC3 narrow

nsec3param : string

The NSEC3PARAM record

presigned : boolean

Whether or not the zone is pre-signed

rrsets : array of RRSet

RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the …/zones list endpoint)

serial : integer

The SOA serial number

slave_tsig_key_ids : array of string

The id of the TSIG keys used for slave operation in this zone

soa_edit : string

The SOA-EDIT metadata item

soa_edit_api : string

The SOA-EDIT-API metadata item

type : string

Set to “Zone”

url : string

API endpoint for this zone

zone : string

MAY contain a BIND-style zone file when creating a zone

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

json RRSet : object

RRSet

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

Required members:
name : string

Name for record set (e.g. “www.powerdns.com.”)

records : array of 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).

ttl : integer

DNS TTL of the records, in seconds. MUST NOT be included when changetype is set to “DELETE”.

type : string

Type of this record (e.g. “A”, “PTR”, “MX”)

Optional members:
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.

comments : array of 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.

Comments are per-RRset.

json Comment : object

Comment

A comment about an RRSet.

Optional members:
account : string

Name of an account that added the comment

content : string

The actual comment

modified_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 pdnsutil zone secure and pdnsutil zone rectify (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 ALLOW-DNSUPDATE-FROM, FORWARD-DNSUPDATE, NOTIFY-DNSUPDATE, SOA-EDIT-DNSUPDATE 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 secondary zone, it is recommended to not set any of nameservers, rrsets or zone.

Examples

Listing all zones

GET /api/v1/servers/localhost/zones HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

[{"account": "", "dnssec": false, "edited_serial": 2022040504, "id": "example.org.", "kind": "Native", "last_check": 0, "masters": [], "name": "example.org.", "notified_serial": 0, "serial": 2022040504, "url": "/api/v1/servers/localhost/zones/example.org."}]

Creating new zone

POST /api/v1/servers/localhost/zones HTTP/1.1
X-API-Key: secret
Content-Type: application/json

{"name": "example.org.", "kind": "Native", "masters": [], "nameservers": ["ns1.example.org.", "ns2.example.org."]}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

{"account": "", "api_rectify": false, "dnssec": false, "edited_serial": 2022040501, "id": "example.org.", "kind": "Native", "last_check": 0, "master_tsig_key_ids": [], "masters": [], "name": "example.org.", "notified_serial": 0, "nsec3narrow": false, "nsec3param": "", "rrsets": [{"comments": [], "name": "example.org.", "records": [{"content": "a.misconfigured.dns.server.invalid. hostmaster.example.org. 2022040501 10800 3600 604800 3600", "disabled": false}], "ttl": 3600, "type": "SOA"}, {"comments": [], "name": "example.org.", "records": [{"content": "ns1.example.org.", "disabled": false}, {"content": "ns2.example.org.", "disabled": false}], "ttl": 3600, "type": "NS"}], "serial": 2022040501, "slave_tsig_key_ids": [], "soa_edit": "", "soa_edit_api": "DEFAULT", "url": "/api/v1/servers/localhost/zones/example.org."}

Listing a zone

GET /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

{"account": "", "api_rectify": false, "dnssec": false, "edited_serial": 2022040501, "id": "example.org.", "kind": "Native", "last_check": 0, "master_tsig_key_ids": [], "masters": [], "name": "example.org.", "notified_serial": 0, "nsec3narrow": false, "nsec3param": "", "rrsets": [{"comments": [], "name": "example.org.", "records": [{"content": "a.misconfigured.dns.server.invalid. hostmaster.example.org. 2022040501 10800 3600 604800 3600", "disabled": false}], "ttl": 3600, "type": "SOA"}, {"comments": [], "name": "example.org.", "records": [{"content": "ns1.example.org.", "disabled": false}, {"content": "ns2.example.org.", "disabled": false}], "ttl": 3600, "type": "NS"}], "serial": 2022040501, "slave_tsig_key_ids": [], "soa_edit": "", "soa_edit_api": "DEFAULT", "url": "/api/v1/servers/localhost/zones/example.org."}

Deleting a zone

DELETE /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 204 No Content

Creating new RRset

PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret
Content-Type: application/json

{"rrsets": [{"name": "test.example.org.", "type": "A", "ttl": 3600, "changetype": "REPLACE", "records": [{"content": "192.168.0.5", "disabled": false}]}]}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 204 No Content

Adding a single record to a RRset

Note

added in versions 4.9.12 and 5.0.2

PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret
Content-Type: application/json

{"rrsets": [{"name": "test.example.org.", "type": "TXT", "changetype": "EXTEND", "records": [{"content": "the contents of the records to add", "disabled": false}]}]}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 204 No Content

If a record with the same exact content already exists in the RRSet, no action is performed and no error is returned.

Deleting a RRset

PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret
Content-Type: application/json

{"rrsets": [{"name": "test.example.org.", "type": "A", "changetype": "DELETE"}]}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 204 No Content

If no record with the same exact content exists in the RRSet, no action is performed and no error is returned.

Deleting a single record from a RRset

Note

added in versions 4.9.12 and 5.0.2

PATCH /api/v1/servers/localhost/zones/example.org. HTTP/1.1
X-API-Key: secret
Content-Type: application/json

{"rrsets": [{"name": "test.example.org.", "type": "TXT", "changetype": "PRUNE", "records": [{"content": "the contents of the records to delete"}]}]}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 204 No Content

Rectifying a zone

PUT /api/v1/servers/localhost/zones/example.org./rectify HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

{"result": "Rectified"}