API

We have two different APIs - the PowerDNS-compatible API proxy, described lower on this page, and a simpler Dynamic DNS endpoint. For DynDNS, see this page instead.

Supported clients

Our API is compatible with a subset of the PowerDNS API. You can find more information about their endpoints in their official documentation. This allows for using an array of already available clients and libraries, including integrations with ACME/certbot.

The following lists clients which are "known, working, and battle-tested":

If you're using a library or client which is not listed here, mention it on our IRC channel. Help with debugging broken clients is also heavily appreciated - we're always grateful for incompatibility reports and debug logs :)

Endpoints

The API is exposed under https://beta.servfail.network/api/v1/. Please note that depending on the library, it will either require the URL above, or just https://beta.servfail.network/.

The following endpoints are supported:

{server} is one of our NSes (including the canonical trailing dot) and {zone} is your domain (also with the canonical dot). Some PowerDNS libraries strip the canonical dot from the URL, which is accepted by PowerDNS itself, but not by our API proxy; Work on creating a fix for this is already underway.

As an example, the URL for requesting a zone may look like this:

https://beta.servfail.network/api/v1/servers/miyuki.sakamoto.pl./zones/sdomi.pl.

Authentication

To get the X-API-Key, go to servfail-web's settings page and generate an API token. For now, this token has full access to all resources available to the account; More granular access, and multiple tokens per account are on our TODO list.

Examples

We don't provide advanced usage examples directly. Please check out PowerDNS docs for this purpose.

For a basic way to check if your token works, use this curl invocation:

curl -H 'X-Api-Key: {token}' https://beta.servfail.network/api/v1/