@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api PowerDNS Authoritative HTTP API
@base /api/v1
@version 0.0.18
@auth ApiKey X-API-Key in header
@endpoints 43
@hint download_for_search
@toc error(1), servers(42)

@group error
@endpoint GET /error
@desc Will always generate an error

@endgroup

@group servers
@endpoint GET /servers
@desc List all servers
@returns(200) An array of servers

@endpoint GET /servers/{server_id}
@desc List a server
@returns(200) {type: str, id: str, daemon_type: str, version: str, url: str, config_url: str, zones_url: str} # An server

@endpoint PUT /servers/{server_id}/cache/flush
@desc Flush a cache-entry by name
@required {domain: str # The domain name to flush from the cache}
@returns(200) {count: num, result: str} # Flush successful

@endpoint GET /servers/{server_id}/zones
@desc List all Zones in a server
@optional {zone: str # 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: bool=true # “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.}
@returns(200) An array of Zones

@endpoint POST /servers/{server_id}/zones
@desc Creates a new domain, returns the Zone on creation.
@optional {rrsets: bool=true # “true” (default) or “false”, whether to include the “rrsets” in the response Zone object., id: str # Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs., name: str # Name of the zone (e.g. “example.com.”) MUST have a trailing dot, type: str # Set to “Zone”, url: str # API endpoint for this zone, kind: str(Native/Master/Slave/Producer/Consumer) # Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”, rrsets: [map{name!: str, type!: str, ttl!: int, changetype: str, records!: [map], comments: [map]}] # RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the .../zones list endpoint), serial: int # The SOA serial number, notified_serial: int # The SOA serial notifications have been sent out for, edited_serial: int # The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings, masters: [str] # List of IP addresses configured as a master for this zone (“Slave” type zones only), dnssec: bool # 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: str # The NSEC3PARAM record, nsec3narrow: bool # Whether or not the zone uses NSEC3 narrow, presigned: bool # Whether or not the zone is pre-signed, soa_edit: str # The SOA-EDIT metadata item, soa_edit_api: str # The SOA-EDIT-API metadata item, api_rectify: bool # Whether or not the zone will be rectified on data changes via the API, zone: str # MAY contain a BIND-style zone file when creating a zone, catalog: str # The catalog this zone is a member of, account: str # MAY be set. Its value is defined by local policy, nameservers: [str] # 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., master_tsig_key_ids: [str] # The id of the TSIG keys used for master operation in this zone, slave_tsig_key_ids: [str] # The id of the TSIG keys used for slave operation in this zone, last_check: int}
@returns(201) {id: str, name: str, type: str, url: str, kind: str, rrsets: [map], serial: int, notified_serial: int, edited_serial: int, masters: [str], dnssec: bool, nsec3param: str, nsec3narrow: bool, presigned: bool, soa_edit: str, soa_edit_api: str, api_rectify: bool, zone: str, catalog: str, account: str, nameservers: [str], master_tsig_key_ids: [str], slave_tsig_key_ids: [str], last_check: int} # A zone

@endpoint GET /servers/{server_id}/zones/{zone_id}
@desc zone managed by a server
@optional {rrsets: bool=true # “true” (default) or “false”, whether to include the “rrsets” in the response Zone object., rrset_name: str # Limit output to RRsets for this name., rrset_type: str # Limit output to the RRset of this type. Can only be used together with rrset_name., include_disabled: bool # “true” (default) or “false”, whether to include disabled RRsets in the response.}
@returns(200) {id: str, name: str, type: str, url: str, kind: str, rrsets: [map], serial: int, notified_serial: int, edited_serial: int, masters: [str], dnssec: bool, nsec3param: str, nsec3narrow: bool, presigned: bool, soa_edit: str, soa_edit_api: str, api_rectify: bool, zone: str, catalog: str, account: str, nameservers: [str], master_tsig_key_ids: [str], slave_tsig_key_ids: [str], last_check: int} # A Zone

@endpoint DELETE /servers/{server_id}/zones/{zone_id}
@desc Deletes this zone, all attached metadata and rrsets.
@returns(204) Returns 204 No Content on success.

@endpoint PATCH /servers/{server_id}/zones/{zone_id}
@desc Creates/modifies/deletes RRsets present in the payload and their comments. Returns 204 No Content on success.
@optional {id: str # Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs., name: str # Name of the zone (e.g. “example.com.”) MUST have a trailing dot, type: str # Set to “Zone”, url: str # API endpoint for this zone, kind: str(Native/Master/Slave/Producer/Consumer) # Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”, rrsets: [map{name!: str, type!: str, ttl!: int, changetype: str, records!: [map], comments: [map]}] # RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the .../zones list endpoint), serial: int # The SOA serial number, notified_serial: int # The SOA serial notifications have been sent out for, edited_serial: int # The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings, masters: [str] # List of IP addresses configured as a master for this zone (“Slave” type zones only), dnssec: bool # 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: str # The NSEC3PARAM record, nsec3narrow: bool # Whether or not the zone uses NSEC3 narrow, presigned: bool # Whether or not the zone is pre-signed, soa_edit: str # The SOA-EDIT metadata item, soa_edit_api: str # The SOA-EDIT-API metadata item, api_rectify: bool # Whether or not the zone will be rectified on data changes via the API, zone: str # MAY contain a BIND-style zone file when creating a zone, catalog: str # The catalog this zone is a member of, account: str # MAY be set. Its value is defined by local policy, nameservers: [str] # 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., master_tsig_key_ids: [str] # The id of the TSIG keys used for master operation in this zone, slave_tsig_key_ids: [str] # The id of the TSIG keys used for slave operation in this zone, last_check: int}
@returns(204) Returns 204 No Content on success.

@endpoint PUT /servers/{server_id}/zones/{zone_id}
@desc Modifies basic zone data.
@optional {id: str # Opaque zone id (string), assigned by the server, should not be interpreted by the application. Guaranteed to be safe for embedding in URLs., name: str # Name of the zone (e.g. “example.com.”) MUST have a trailing dot, type: str # Set to “Zone”, url: str # API endpoint for this zone, kind: str(Native/Master/Slave/Producer/Consumer) # Zone kind, one of “Native”, “Master”, “Slave”, “Producer”, “Consumer”, rrsets: [map{name!: str, type!: str, ttl!: int, changetype: str, records!: [map], comments: [map]}] # RRSets in this zone (for zones/{zone_id} endpoint only; omitted during GET on the .../zones list endpoint), serial: int # The SOA serial number, notified_serial: int # The SOA serial notifications have been sent out for, edited_serial: int # The SOA serial as seen in query responses. Calculated using the SOA-EDIT metadata, default-soa-edit and default-soa-edit-signed settings, masters: [str] # List of IP addresses configured as a master for this zone (“Slave” type zones only), dnssec: bool # 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: str # The NSEC3PARAM record, nsec3narrow: bool # Whether or not the zone uses NSEC3 narrow, presigned: bool # Whether or not the zone is pre-signed, soa_edit: str # The SOA-EDIT metadata item, soa_edit_api: str # The SOA-EDIT-API metadata item, api_rectify: bool # Whether or not the zone will be rectified on data changes via the API, zone: str # MAY contain a BIND-style zone file when creating a zone, catalog: str # The catalog this zone is a member of, account: str # MAY be set. Its value is defined by local policy, nameservers: [str] # 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., master_tsig_key_ids: [str] # The id of the TSIG keys used for master operation in this zone, slave_tsig_key_ids: [str] # The id of the TSIG keys used for slave operation in this zone, last_check: int}
@returns(204) Returns 204 No Content on success.

@endpoint PUT /servers/{server_id}/zones/{zone_id}/notify
@desc Send a DNS NOTIFY to all slaves.
@returns(200) OK

@endpoint PUT /servers/{server_id}/zones/{zone_id}/axfr-retrieve
@desc Retrieve slave zone from its master.
@returns(200) OK

@endpoint GET /servers/{server_id}/zones/{zone_id}/export
@desc Returns the zone in AXFR format.
@returns(200) OK

@endpoint PUT /servers/{server_id}/zones/{zone_id}/rectify
@desc Rectify the zone data.
@returns(200) OK

@endpoint GET /servers/{server_id}/config
@desc Returns all ConfigSettings for a single server
@returns(200) List of config values

@endpoint GET /servers/{server_id}/config/{config_setting_name}
@desc Returns a specific ConfigSetting for a single server
@returns(200) {name: str, type: str, value: str} # List of config values

@endpoint GET /servers/{server_id}/statistics
@desc Query statistics.
@optional {statistic: str # When set to the name of a specific statistic, only this value is returned. If no statistic with that name exists, the response has a 422 status and an error message., includerings: bool=true # “true” (default) or “false”, whether to include the Ring items, which can contain thousands of log messages or queried domains. Setting this to ”false” may make the response a lot smaller.}
@returns(200) List of Statistic Items
@errors {422: Returned when a non-existing statistic name has been requested. Contains an error message}

@endpoint GET /servers/{server_id}/search-data
@desc Search the data inside PowerDNS
@required {q: str # The string to search for, max: int # Maximum number of entries to return}
@optional {object_type: str # Type of data to search for, one of “all”, “zone”, “record”, “comment”}
@returns(200) Returns a JSON array with results

@endpoint GET /servers/{server_id}/zones/{zone_id}/metadata
@desc Get all the Metadata associated with the zone.
@returns(200) List of Metadata objects

@endpoint POST /servers/{server_id}/zones/{zone_id}/metadata
@desc Creates a set of metadata entries
@optional {kind: str # Name of the metadata, metadata: [str] # Array with all values for this metadata kind.}
@returns(204) OK

@endpoint GET /servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}
@desc Get the content of a single kind of domain metadata as a Metadata object.
@returns(200) {kind: str, metadata: [str]} # Metadata object with list of values

@endpoint PUT /servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}
@desc Replace the content of a single kind of domain metadata.
@returns(200) {kind: str, metadata: [str]} # Metadata object with list of values

@endpoint DELETE /servers/{server_id}/zones/{zone_id}/metadata/{metadata_kind}
@desc Delete all items of a single kind of domain metadata.
@returns(204) OK

@endpoint GET /servers/{server_id}/zones/{zone_id}/cryptokeys
@desc Get all CryptoKeys for a zone, except the privatekey
@returns(200) List of Cryptokey objects

@endpoint POST /servers/{server_id}/zones/{zone_id}/cryptokeys
@desc Creates a Cryptokey
@optional {type: str # set to "Cryptokey", id: int # The internal identifier, read only, keytype: str(ksk/zsk/csk), active: bool # Whether or not the key is in active use, published: bool # Whether or not the DNSKEY record is published in the zone, dnskey: str # The DNSKEY record for this key, ds: [str] # An array of DS records for this key, cds: [str] # An array of DS records for this key, filtered by CDS publication settings, privatekey: str # The private key in ISC format, algorithm: str # The name of the algorithm of the key, should be a mnemonic, bits: int # The size of the key}
@returns(201) {type: str, id: int, keytype: str, active: bool, published: bool, dnskey: str, ds: [str], cds: [str], privatekey: str, algorithm: str, bits: int} # Created

@endpoint GET /servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}
@desc Returns all data about the CryptoKey, including the privatekey.
@returns(200) {type: str, id: int, keytype: str, active: bool, published: bool, dnskey: str, ds: [str], cds: [str], privatekey: str, algorithm: str, bits: int} # Cryptokey

@endpoint PUT /servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}
@desc This method (de)activates a key from zone_name specified by cryptokey_id
@returns(204) OK

@endpoint DELETE /servers/{server_id}/zones/{zone_id}/cryptokeys/{cryptokey_id}
@desc This method deletes a key specified by cryptokey_id.
@returns(204) OK

@endpoint GET /servers/{server_id}/tsigkeys
@desc Get all TSIGKeys on the server, except the actual key
@returns(200) List of TSIGKey objects

@endpoint POST /servers/{server_id}/tsigkeys
@desc Add a TSIG key
@optional {name: str # The name of the key, id: str # The ID for this key, used in the TSIGkey URL endpoint., algorithm: str # The algorithm of the TSIG key, key: str # The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material, type: str # Set to "TSIGKey"}
@returns(201) {name: str, id: str, algorithm: str, key: str, type: str} # Created
@errors {409: An item with this name already exists}

@endpoint GET /servers/{server_id}/tsigkeys/{tsigkey_id}
@desc Get a specific TSIGKeys on the server, including the actual key
@returns(200) {name: str, id: str, algorithm: str, key: str, type: str} # OK.

@endpoint PUT /servers/{server_id}/tsigkeys/{tsigkey_id}
@desc The TSIGKey at tsigkey_id can be changed in multiple ways:
@optional {name: str # The name of the key, id: str # The ID for this key, used in the TSIGkey URL endpoint., algorithm: str # The algorithm of the TSIG key, key: str # The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material, type: str # Set to "TSIGKey"}
@returns(200) {name: str, id: str, algorithm: str, key: str, type: str} # OK. TSIGKey is changed.
@errors {409: An item with this name already exists}

@endpoint DELETE /servers/{server_id}/tsigkeys/{tsigkey_id}
@desc Delete the TSIGKey with tsigkey_id
@returns(204) OK, key was deleted

@endpoint GET /servers/{server_id}/autoprimaries
@desc Get a list of autoprimaries
@returns(200) {ip: str, nameserver: str, account: str} # OK.

@endpoint POST /servers/{server_id}/autoprimaries
@desc Add an autoprimary
@optional {ip: str # IP address of the autoprimary server, nameserver: str # DNS name of the autoprimary server, account: str # Account name for the autoprimary server}
@returns(201) Created

@endpoint DELETE /servers/{server_id}/autoprimaries/{ip}/{nameserver}
@desc Delete the autoprimary entry
@returns(204) OK, key was deleted

@endpoint GET /servers/{server_id}/views
@desc List all views in a server
@required {server_id: str # The id of the server to retrieve}
@returns(200) {views: [str]} # An array of view names

@endpoint GET /servers/{server_id}/views/{view}
@desc List the contents of a given view
@returns(200) {zones: [str]} # An array of zone names

@endpoint POST /servers/{server_id}/views/{view}
@desc Adds a zone to a given view, creating it if needed
@optional {name: str # The zone to add to the view}
@returns(204) Returns 204 No Content on success.

@endpoint DELETE /servers/{server_id}/views/{view}/{id}
@desc Removes the given zone from the given view
@returns(204) Returns 204 No Content on success.

@endpoint GET /servers/{server_id}/networks
@desc List all registered networks and views in a server
@returns(200) {networks: [map]} # An array of networks

@endpoint GET /servers/{server_id}/networks/{ip}/{prefixlen}
@desc Return the view associated to the given network
@returns(200) {network: str, view: str} # A network

@endpoint PUT /servers/{server_id}/networks/{ip}/{prefixlen}
@desc Sets the view associated to the given network
@optional {view: str # The name of the view to use for this network}
@returns(204) Returns 204 No Content on success.

@endgroup

@end