Primary DNS API v1

This documentation describes the legacy DNS API. It is recommended that new users use DNS API v2.

Our Primary DNS service can be manually configured through the Customer Control Panel For many applications, you may want to script additions, updates and deletions of primary DNS resource records. This can be done using our API. For example, you could use the Primary DNS API to:

  • implement DNS-based failover for your site;
  • implement a dynamic DNS system;
  • use DNS to redirect to a holding page during site maintenance.

Authentication

In order to use the API, you must set a password in the control panel interface for your domain that you wish to manage, using the DNS API option.

Note that this API uses separate, per-domain credentials. API keys for DNS API v2 cannot be used with this API.

Making requests

Requests to the API take the form of an HTTP request containing a number of HTTP parameters. These are documented below. HTTP requests should be made to:

  • https://dnsapi.mythic-beasts.com/

IPv4 and IPv6 only versions of this service are also available:

  • https://dnsapi4.mythic-beasts.com/ (IPv4-only)
  • https://dnsapi6.mythic-beasts.com/ (IPv6-only)

These IP-version specific URLs are useful when using the DYNAMIC_IP parameter to construct a Dynamic DNS service.

The request can be made using either a GET request, with parameters in the query string, or a POST request, with parameters specified in an application/x-www-form-urlencoded request body. However, we would always recommend POST, as otherwise your domain API password will appear unencrypted in the URL of the request.

HTTP parameters

domain
Required. The domain name you are updating the zonefile for, e.g. mythic-beasts.com
password
Required. The password set in the control panel for the domain.
command
Required. An API command. Commands take the form of a verb followed by a zone file entry as appropriate. This parameter can be repeated to perform multiple commands in a single transaction.
origin
Optional. The suffix to be appended to the hostname given in commands. By default, this will be your domain name. Specifying a value of . allows you to provide fully qualified hostnames in your commands.

Commands

All the commands in the request parameter are processed in order. The commands allowed are as follows.

Add

The ADD command requests that an entry be added to the zone file. This command can take any of the following forms:

ADD host ttl type data
ADD host ttl MX mx_priority data
ADD host ttl SRV srv_priority srv_weight srv_port data

For example:

ADD www 86400 A 93.93.130.49

If successful, the response will contain ADD followed by the entry. Otherwise, the response will contain NADD followed by the entry and a reason that the update didn't succeed. For example:

NADD www 86400 A 93.93.130.49; Can't have multiple identical records

DELETE

The DELETE command requests that an entry be removed from the zone. Valid syntax for this command is

DELETE host ttl type data
DELETE host ttl MX mx_priority data
DELETE host ttl SRV srv_priority srv_weight srv_port data

For example:

DELETE www 86400 A 93.93.130.49

The response will contain DELETE followed by the entry in the event of success, and NDELETE followed by the entry and a reason in the event of failure.

LIST

The LIST command takes no arguments, and requests a list of all the entries in the zone. For example:

@ 86400 NS ns0.mythic-beasts.com.
@ 86400 MX 10 mx2.mythic-beasts.com.
@ 86400 A 93.93.130.44
@ 86400 NS ns0.beasts.org.
@ 86400 NS ns1.mythic-beasts.com.

REPLACE

The REPLACE command takes a new record as argument, and replaces all existing records, if any, for the same host and type (and, if relevant, MX priority) with the new record provided. This is the easiest way to implement Dynamic DNS using the API.

For example:

REPLACE www 300 A 93.93.130.49

This will delete all existing A records for "www" and replace them with the provided record.

You can also substitute the IP address for DYNAMIC_IP, and the service will use the client's IP address.

Examples:

REPLACE home 300 A DYNAMIC_IP
REPLACE home 300 AAAA DYNAMIC_IP

You'll need to make sure you are connecting to the API over the correct IP version for this to work. Use https://dnsapi4.mythic-beasts.com or https://dnsapi6.mythic-beasts.com, for IPv4 or IPv6 records respectively.

Note that the REPLACE command potentially replaces multiple records with a single record. If this is an issue, you should use combinations of DELETE and ADD commands instead.

Transactions

Each HTTP request is treated as an atomic transaction, meaning that either all commands succeed or none of them do, and that there is no danger of the DNS zone being updated with the result of only some of the commands being applied. This means that, with the exception of ANAME records, you can safely change a record by putting a DELETE followed by an ADD into the same HTTP request.

If a transaction is aborted because a later command fails, then the response will include positive acknowledgements of the earlier commands, but their results will not be committed. You can check the overall status of the request using the HTTP response code which will be 200 in the event of success, and a 4xx code in the event of a failure.

Note that when an ANAME record is deleted, any A and AAAA records that it has generated will be removed immediately, but it may be a number of minutes before records are generated for any new ANAME records that it is replaced with.

Updates

We update our DNS servers every minute, so changes should generally be visible on our servers within a minute or so. The DNS system relies heavily on caching, so requests made via other DNS servers may take much longer to take effect. You can control this using the TTL field on records.

Sample code

curl

API updates can be made using the curl command line utility:

curl --data "domain=MY_DOMAIN&password=MY_PASSWORD&command=LIST" \
https://dnsapi.mythic-beasts.com/

wget

wget -q -O- '--post-data=domain=MY_DOMAIN;password=MY_PASSWORD;command=ADD wibble 300 TXT foobar;command=LIST'

As the second example demonstrates, you can use either ampersand & or semicolon ; to separate parameters. Send more than one command by using multiple command= parameters.

Perl

#!/usr/bin/perl -w

use WWW::Mechanize;

my $domain = 'mythic-beasts.com';
my $password = 'this-is-actually-a-secret';
my $url = 'https://dnsapi.mythic-beasts.com/';

my $mech = new WWW::Mechanize;
print "Zone\n\n";

$mech->post($url,
        { domain => $domain, password => $password, command => 'LIST' }
);
print $mech->content();

Python

#!/usr/bin/env python3

import urllib.request
import urllib.parse

yourDomain = "example.com"

yourDomainAPIPass = "password"

url = 'https://dnsapi.mythic-beasts.com/'

values = {'domain'  : yourDomain,
          'password' : yourDomainAPIPass,
          'command'  : 'LIST' }

data = urllib.parse.urlencode(values).encode('utf-8')
req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
responseContents = response.read().decode("utf-8")
print(responseContents)

Applications

We have published a hook for dehydrated which uses the DNS API to answer ACME challenges.

One of our customers has written a script to synchronize zone data to our servers.