Primary DNS API v2

OpenAPI YAML

This API allows you to manage DNS records for your domains (or "zones") programmatically. If you are new to using this API, we recommend that you start with the tutorial, which demonstrates the main features of the API.

This documentation describes version 2 of the API. If you are using the previous version of the API, you should consult the DNS API v1 documentation

Authentication and authorisation

This API uses our auth service. Credentials for using this API can be obtained from the API Keys section of the control panel. Credentials can be unrestricted, allowing them to manage all zones on your account, or restricted to individual zones, records and record types.

Authentication for the DNS API can be done using a "Bearer token". In this, you provide your credentials to the auth service which will return a token which can be used in subsequent requests. See the documentation for the auth service for more details.

The DNS API also support HTTP Basic Auth. When using Basic Auth, credentials are provided directly to the DNS API. See the tutorial for details of how to do this using curl.

Please note that this API uses different credentials to DNS API v1. Credentials for DNS API v1 will not work with this API and vice versa.

API overview

Terminology: zones vs domains

DNS records are divided up into zones. In most cases, zones correspond directly to domains, so there will be a single example.com zone for the example.com domain.

It is possible to divide a single domain into multiple zones, which may be used delegate control of the DNS for a portion of a domain. Therefore the API, and this documentation, use the term zone rather than domain.

Selecting records

DNS records can be selected by the combination of a hierarchical URL and an optional filter. For example the following URL selects the A records for www.example.com:

/zones/example.com/records/www/A

The type and hostname can be omitted. The following URL will select all records for www.example.com, regardless of type:

/zones/example.com/records/www

It also possible to get all records for the zone:

/zones/example.com/records

An optional filter can be added to select records based on any field. For example, the following will select the same records as the first URL:

/zones/example.com/records?host=www&type=A

Filters can be used on other fields. For example, to select all MX records with a specific priority, use the mx_priority field:

/zones/example.com/records/@/MX?mx_priority=10

Interacting with records

HTTP methods can be used to interact with selected records:

  • A GET request will return details of the selected records.
  • A PUT request will replace the selected records.
  • A POST request will add to the selected records.
  • A DELETE request will delete the selected records.

Input and output formats

The API supports JSON and RFC 1035 zone file format for both input and output. The default is JSON (application/json). Zone file format can be selected by specifying:

  • A Content-Type: text/dns header for input (PUT and POST requests)
  • An Accept: text/dns header for output (GET requests)

In addition, new records can be defined as form data using the application/x-www-form-urlencoded content type. This is less powerful because only a single record can be defined in each request.

Updating records

Records can be created or updated by making either a PUT or POST request, and supplying the new records as input.

In the case of a POST request, any records provided are added to the zone. In the case of a PUT request, all records selected by the URL are replaced by the provided input.

Note that when performing a PUT or POST request, new records must match any host and record type specified by the hierarchical part of URL but are not required to match the details of any filters.

Transactions

Update operations within a request are atomic. Either all records selected and supplied will be updated, or the operation will fail and no records are updated. It is also guaranteed that all records updated in a single request will add to the DNS server in a single update.

The same is not true of updates made over multiple requests. If you delete old records in one request, and add new records in a subsequent request, it is possible that the DNS server will be updated between these requests, and your zone will contain neither the old nor new records.

ANAME records

ANAME records are updated by a separate, periodic process:

  • If you create a new ANAME record, generated A and AAAA records will not appear immediately.

  • If you replace an ANAME record with a new ANAME record for the same hostname, any existing, generated A and AAAA records will remain in place until the next regular update.

  • If you remove an ANAME record, and do not replace it, generated records will be removed immediately.

Fields

The different parts of a record are referred to as fields. Some fields are common to all record types:

  • host - the name of the record being defined, within the zone. Note that this name is relative to the zone name.
  • ttl - the TTL ("time to live") specified in seconds.
  • type - the record type (e.g. A or MX).
  • data - the data defined for the record.

Some record types take additional fields. A full list of supported record types, and the fields that they take, can be obtained from the /record-types end point. Note that the order that the fields are specified in for each record type corresponds to the order of the fields in zone file format.

Filtering

As noted above, record URLs can be filtered. This can be done using a "basic filter", specifying the field names directly as query parmeters. For example, the following query string will select all MX records with a TTL of 300:

?ttl=300&type=MX

Combining filters

It is also possible to combine multiple filters in a single request. This is done by taking a basic filter, URL encoding it, and passing it as a value to the select parameter. Multiple filters can be specified by repeating the select parameter.

The combined filter will return any records that match all of the criteria in at least one select parameter. For example:

?select=type%3DA%26host=www4&select=type%3DAAAA%26host=www6

The above filter will select all A records for www4 and all AAAA records for www6.

Combining filters makes it possible to select any subset of the records in a zone.

Boolean query parameters

The API has a number of boolean query string parameters. "True" can be indicated with true, 1 or omitting the value altogether. For example:

  • ?exclude-generated
  • ?exclude-generated=true
  • ?exclude-generated=1

Base URL

The base URL for this service is:

  • https://api.mythic-beasts.com/dns/v2

The endpoints listed below should be appended to the above URL. In addition, the service is available on IPv4-only and IPv6-only URLs:

  • https://ipv4.api.mythic-beasts.com/dns/v2
  • https://ipv6.api.mythic-beasts.com/dns/v2

These URLs are intend for use with Dynamic DNS, so that your IPv4 or IPv6 address can be detected correctly.

Endpoints

get /record-types

https://api.mythic-beasts.com/dns/v2/record-types

Lists the supported record types, and the field names applicable to each type.

Responses

CodeDescription
200

List of supported record types, and the field names application to each type. If the verify parameter was specified, this indicates that all authoritative servers returned the latest version of the selected records, as included in the response.

application/json

NameDescription
record_types object

Available field names by record type
* array

Available field names for record type
Example
{
    "record_types": {
        "A": [
            "host",
            "ttl",
            "type",
            "data"
        ],
        "AAAA": [
            "host",
            "ttl",
            "type",
            "data"
        ],
        "MX": [
            "host",
            "ttl",
            "type",
            "mx_priority",
            "data"
        ]
    }
}

get /zones

https://api.mythic-beasts.com/dns/v2/zones

List all zones to which the current API key has at least some level of access.

If the key is unrestricted, it will list all zones on the customer account.

Responses

CodeDescription
200

List of zones

application/json

NameDescription
zones array

List of zones
Example
{
    "zones": [
        "example1.com",
        "example2.com"
    ]
}
401 Not authenticated
403 Not authorised

get /zones/{zone}/records

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records

get /zones/{zone}/records/{host}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}

get /zones/{zone}/records/{host}/{type}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}/{type}

List records in the zone.

This will return all records that match the specified path, filtered according to query string parameters. The response can be returned in JSON format, or RFC 1035 zone file format. The response format can be selected using an Accept header of application/json or text/dns, respectively.

Parameters

NameLocationDescription
zone string path

The name of the zone.
type string path

The record type. Must be upper case. See record types end point for a list of supported record types.
host string path

The host for records to return. Use @ to return records for the bare domain (apex).
verify boolean query

Verify that all authoritative servers are returning the latest record details.

If all authoritative servers return the latest version of the selected records, this will give a 200 response, with details of the records.

Otherwise, this will give a 409 response, with details of the differences between live and expected records.

This parameter can only be used if host and type are specified in the request URL.
Common query parameters query

Common record selection parameters.
Record filters query

Common parameters for filtering records.

Responses

CodeDescription
200

List of records

application/json

NameDescription
records array

List of records
Example
{
    "records": [
        {
            "host": "www",
            "ttl": 300,
            "type": "A",
            "data": "1.2.3.4"
        },
        {
            "host": "@",
            "ttl": 300,
            "type": "MX",
            "mx_priority": 10,
            "data": "mx.mythic-beasts.com."
        }
    ]
}

text/dns

www 300  A   1.2.3.4
@   300  MX  10 mx.mythic-beasts.com.
409

Indicates that the response from one or more authoritative nameservers does not match the latest version of the selected records. Only returned if the verify parameter is specified.

application/json

NameDescription
errors array

List of errors
Example
{
    "errors": [
        "'1.2.3.4' not found in response from ns1.mythic-beasts.com."
    ]
}
401 Not authenticated
403 Not authorised

post /zones/{zone}/records

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records

post /zones/{zone}/records/{host}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}

post /zones/{zone}/records/{host}/{type}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}/{type}

Add new records to a zone.

New records can be provided as JSON (application/json), RFC1035 format (text/dns), or form parameters (application/x-www-form-urlencoded).

If the URL path contains host or type parameters, new records must match these values.

Changes are applied atomically; either all new records will be added, or none of them will and an error will be returned (see transactions).

Parameters

NameLocationDescription
zone string path

The name of the zone.
type string path

The record type. Must be upper case. See record types end point for a list of supported record types.
host string path

The host for records to return. Use @ to return records for the bare domain (apex).
Common query parameters query

Common record selection parameters.
Record filters query

Common parameters for filtering records.

Request Body JSON

NameDescription
records array

(Optional) List of records to add.
host string

(Optional) Hostname of record to add.
ttl number

(Optional) TTL (time-to-live) value
type string

(Optional) Record type
data string

(Optional) Record data. A and AAAA records can additionally take the special value DYNAMIC_IP which uses the client's IP address as the field value. Hex strings (for SSHFP and TLSA) must be in lower-case.
Additional fields
Additional type-specific fields for record creation
Example

application/json

{
    "records": [
        {
            "host": "www",
            "ttl": 300,
            "type": "CNAME",
            "data": "proxy.mythic-beasts.com."
        }
    ]
}

Request Body Form

NameDescription
host string

(Optional) Hostname of record to add. Required if not specified in the URL.
ttl number

(Optional) TTL (time-to-live) value
type string

(Optional) Record type. Required if not specified in the URL.
data string

(Optional) Record data. This parameter may be repeated, which will create multiple records with the same name and type (and the same values for any additional fields). Hex strings (for SSHFP and TLSA) must be in lower-case.
Additional fields
Additional type-specific fields for record creation

Request Body Zone

Data may be submitted as an RFC1035 formatted zone file. The order of TTL and record type is interchangeable. TTL may be omitted. If a line starts with space, the previous hostname will be used. The order of otherwise be as returned by the record types end point.

Example

text/dns

www 300  A   1.2.3.4
@   300  MX  10 mx.mythic-beasts.com.

Responses

CodeDescription
200

Records added

application/json

NameDescription
records_added integer

Number of records added
message string

Response message
Example
{
    "records_added": 4,
    "message": "4 records added"
}
400 Bad input
401 Not authenticated
403 Not authorised

put /zones/{zone}/records

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records

put /zones/{zone}/records/{host}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}

put /zones/{zone}/records/{host}/{type}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}/{type}

Replaces all records selected by the path and any filters with the provided new records. If no records are matched by the path and filters, the new records will still be added.

New records can be provided as JSON (application/json), RFC1035 format (text/dns), or form parameters (application/x-www-form-urlencoded).

If the URL path contains host or type parameters, new records must match these values.

Changes are applied atomically; either all selected records will be replaced with all new records, or no changes will be made and an error will be returned (see transactions).

Note that zones may contain generated records (typically generated from ANAME records) and template records (common records inherited from a standard template). These records cannot be deleted or replaced, and a PUT request to a URL that would select any such records will result in an error. To avoid this, specify the exclude-generated or exclude-template query parameters.

Parameters

NameLocationDescription
zone string path

The name of the zone.
type string path

The record type. Must be upper case. See record types end point for a list of supported record types.
host string path

The host for records to return. Use @ to return records for the bare domain (apex).
Common query parameters query

Common record selection parameters.
Record filters query

Common parameters for filtering records.

Request Body JSON

NameDescription
records array

(Optional) List of records to add.
host string

(Optional) Hostname of record to add.
ttl number

(Optional) TTL (time-to-live) value
type string

(Optional) Record type
data string

(Optional) Record data. A and AAAA records can additionally take the special value DYNAMIC_IP which uses the client's IP address as the field value. Hex strings (for SSHFP and TLSA) must be in lower-case.
Additional fields
Additional type-specific fields for record creation
Example

application/json

{
    "records": [
        {
            "host": "www",
            "ttl": 300,
            "type": "CNAME",
            "data": "proxy.mythic-beasts.com."
        }
    ]
}

Request Body Form

NameDescription
host string

(Optional) Hostname of record to add. Required if not specified in the URL.
ttl number

(Optional) TTL (time-to-live) value
type string

(Optional) Record type. Required if not specified in the URL.
data string

(Optional) Record data. This parameter may be repeated, which will create multiple records with the same name and type (and the same values for any additional fields). Hex strings (for SSHFP and TLSA) must be in lower-case.
Additional fields
Additional type-specific fields for record creation

Request Body Zone

Data may be submitted as an RFC1035 formatted zone file. The order of TTL and record type is interchangeable. TTL may be omitted. If a line starts with space, the previous hostname will be used. The order of otherwise be as returned by the record types end point.

Example

text/dns

www 300  A   1.2.3.4
@   300  MX  10 mx.mythic-beasts.com.

Responses

CodeDescription
200

Records replaced

application/json

NameDescription
records_added integer

Number of records added
records_removed integer

Number of records removed
message string

Response message
Example
{
    "records_added": 4,
    "records_removed": 3,
    "message": "4 records added"
}
400 Bad input
401 Not authenticated
403 Not authorised

delete /zones/{zone}/records

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records

delete /zones/{zone}/records/{host}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}

delete /zones/{zone}/records/{host}/{type}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/records/{host}/{type}

Deletes all records selected by the path and any specified filters. See the list records endpoint for details of how records are selected.

If no records are selected, the request will return a 200 response and indicate that no records have been removed in the records_removed field.

Parameters

NameLocationDescription
zone string path

The name of the zone.
type string path

The record type. Must be upper case. See record types end point for a list of supported record types.
host string path

The host for records to return. Use @ to return records for the bare domain (apex).
Common query parameters query

Common record selection parameters.
Record filters query

Common parameters for filtering records.

Responses

CodeDescription
200

Records deleted

application/json

NameDescription
records_removed integer

Number of records removed
message string

Response message
Example
{
    "records_removed": 3,
    "message": "3 records removed"
}
400 Bad input
401 Not authenticated
403 Not authorised

put /dynamic/{host}

https://api.mythic-beasts.com/dns/v2/dynamic/{host}

put /zones/{zone}/dynamic/{host}

https://api.mythic-beasts.com/dns/v2/zones/{zone}/dynamic/{host}

This end point will create or update an A or AAAA record with the specified hostname, with the data set to the IP address of the client using the API.

The type of the record will be determined by the type of the IP address. If you connect over IPv6, an AAAA record wil be created. If you connect over IPv4, an A record will be created. You can control how you connect by using the family-specific hostnames.

The TTL of the record is set to 60 seconds.

This end point also supports GET and POST methods with identical behaviour.

In addition to the Basic and Bearer HTTP authentication mechanisms supported by other end points, this endpoint allows the username and password to be provided directly as either form parameters or query string parameters (the latter is not recommended).

Parameters

NameLocationDescription
host string path

The hostname to create or update. If a zone is specified then this can be either the hostname within the zone (e.g. www) or a fully-qualified host name (e.g. www.example.com)
zone string path

The name of the zone. If host is a fully-qualified host name, then this parameter (and the /zones/ prefix) can be omitted.

Request Body Form

NameDescription
username string

(Optional) API key username. This can also be provided as a query parameter, but this is not recommended.
password string

(Optional) API key secret. This can also be provided as a query parameter, but this is not recommended.

Responses

CodeDescription
200

DNS record updated

application/json

NameDescription
message string

Response message
Example
{
    "message": "Dynamic DNS for test set to 2001:db8::1"
}
400 Bad input
401 Not authenticated
403 Not authorised

Parameter groups

Common query parameters

NameLocationDescription
exclude-generated boolean query

Exclude generated records. See boolean query parameters.
exclude-template boolean query

Exclude template records. See boolean query parameters.
comment-aname boolean query

Comment out ANAME pseudo-records in zone file export

If set to true, ANAME records will be prefixed with ; when exported, so that they appear as comments in the zone file export. Note that this option only affects zone file format responses (text/dns), and has no effect on JSON format responses.

Any A or AAAA records generated from ANAME records will still be included uncommented in the response, unless exclude-generated is also specified, in which case they will be omitted altogether.

See boolean query parameters.
select string query

Filter selected records.

Takes a URL-encoded set of record filter query string parameters. Only records matching all specified values will be returned. The select parameter may be repeated in which case, records matching all of the values in any select parameter will be returned. If any record filters are specified directly as query parameters, then these must match in addition to any filters specified in select parameters. See filtering for more details.

Record filters

NameLocationDescription
host string query

Record hostname
type string query

Record type
ttl number query

Time-to-live (TTL). Number of seconds for which the record can be cached
data string query

Record data
mx_priority number query

Record priority (MX records)
srv_priority number query

Record priority (SRV records)
srv_weight number query

Record weight (SRV records)
srv_port number query

Port number (SRV records)
sshfp_algorithm number query

Algorithm for SSH fingerprint (SSHFP records)
sshfp_type number query

SSH fingerprint type (SSHFP records)
caa_flags number query

Flags value (CAA records)
caa_tag string query

CAA tag value (CAA records)
tlsa_usage number query

TLSA usage (0-3) (TLSA records)
tlsa_selector number query

TLSA selector (0 or 1) (TLSA records)
tlsa_matching number query

TLSA match method (0-2) (TLSA records)

Property groups

Additional fields

NameDescription
mx_priority number

(Optional) Record priority (required for MX records)
srv_priority number

(Optional) Record priority (required for SRV records)
srv_weight number

(Optional) Record weight (required for SRV records)
srv_port number

(Optional) Port number (required for SRV records)
sshfp_algorithm number

(Optional) Algorithm for SSH fingerprint (required for SSHFP records)
sshfp_type number

(Optional) SSH fingerprint type (required for SSHFP records)
caa_flags number

(Optional) Flags value (required for CAA records)
caa_tag string

(Optional) CAA tag value (required for CAA records)
tlsa_usage number

(Optional) TLSA usage (0-3) (required for TLSA records)
tlsa_selector number

(Optional) TLSA selector (0 or 1) (required for TLSA records)
tlsa_matching number

(Optional) TLSA match method (0-2) (required for TLSA records)

Common errors

CodeDescription
400

Request cannot be completed due to errors in input.

application/json

NameDescription
errors array

List of errors
Example
{
    "errors": [
        "Unknown record type 'FOO'",
        "SSHFP fingerprint must be an even number of hexadecimal characters."
    ]
}
401

User is not authenticated.

application/json

NameDescription
error string

Error message
Example
{
    "error": "Malformed or missing auth data"
}
403

Not authorised to access this API.

application/json

NameDescription
error string

Error message
Example
{
    "error": "Auth token has no DNS permits"
}

Support Index

Page contents