API

---

Our API is (mostly) compatible with the PowerDNS API. You can find more information about their endpoints in their official documentation. This does offer some nice advantages like the ability to use any ACME/Let's Encrypt client or dynDNS client that already does support the PowerDNS API.

Endpoint

We expose the PowerDNS-compatible API under https://beta.servfail.network/api/v1/servers/{server}/zones/{zone}, where {server} is one of our NSes (including the canonical trailing dot) and {zone} is your domain (also including the canonical dot). A complete URL may for example be:

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

API Key

You can generate an API Key in the settings menu in the Servfail web interface. It is to be used in the same way as the usual PowerDNS API keys: Sent with every request in the X-API-Key HTTP Header.

Example

To update A and AAAA records for the current host one may use a script like this:

#!/usr/bin/env bash

set -eu

declare -a to_update

servfail_api_token=""
servfail_primary="ns1.homecloud.lol"
to_update=("domain1.example.com" "domain2.example.org")

ipv4="$(dig -4 +short A    myip.opendns.com @resolver1.opendns.com)"
ipv6="$(dig -6 +short AAAA myip.opendns.com @resolver1.opendns.com)"

for fqdn in "${to_update[@]}"
do
        host=${fqdn%.*}
        host=${host%.*}
        domain=${fqdn#"${host}."}

        if [[ "${ipv4}" == "$(dig +short A ${host}.${domain} @${servfail_primary})" && "${ipv6}" == "$(dig +short AAAA ${host}.${domain} @${servfail_primary})" ]]; then
                echo "Nothing to do for ${host}.${domain}"
                continue
        fi

        update_json="{
                \"rrsets\": [{
                        \"name\": \"${host}.${domain}.\",
                        \"type\": \"AAAA\",
                        \"ttl\": 300,
                        \"changetype\": \"REPLACE\",
                        \"records\": [{
                                \"content\": \"${ipv6}\",
                                \"disabled\": false
                        }]
                }, {
                        \"name\": \"${host}.${domain}.\",
                        \"type\": \"A\",
                        \"ttl\": 300,
                        \"changetype\": \"REPLACE\",
                        \"records\": [{
                                \"content\": \"${ipv4}\",
                                \"disabled\": false
                        }]
                }]
        }"


        curl -X "PATCH" \
                -d "$update_json" \
                -H "X-API-Key: ${servfail_api_token}" \
                "https://beta.servfail.network/api/v1/servers/${servfail_primary}./zones/${domain}."

done