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

Code Description

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

Name	Description
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

Code Description

200

List of zones

application/json

Name	Description
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

Name	Location	Description
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

Code Description

200

List of records

application/json

Name	Description
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

Name	Description
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

Name	Location	Description
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

Name	Description
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

Name	Description
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

Code Description

200

Records added

application/json

Name	Description
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). These records cannot be deleted, and can be replaced only by an identical set of records. A PUT request to a URL that would delete or change any such records will result in an error. To avoid this, specify the exclude-generated query parameter.

Parameters

Name	Location	Description
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

Name	Description
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

Name	Description
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

Example

text/dns

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

Responses

Code Description

200

Records replaced

application/json

Name	Description
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

Name	Location	Description
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

Code Description

200

Records deleted

application/json

Name	Description
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

Name	Location	Description
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

Name	Description
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

Code Description

200

DNS record updated

application/json

Name	Description
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

Name Location Description

Name	Location	Description
exclude-generated boolean	query	Exclude generated 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.

exclude-generated boolean

query

Exclude generated 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

Name	Location	Description
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

Name	Description
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

Code Description

400

Request cannot be completed due to errors in input.

application/json

Name	Description
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

Name	Description
error string	Error message

Example

{
    "error": "Malformed or missing auth data"
}

403

Not authorised to access this API.

application/json

Name	Description
error string	Error message

Example

{
    "error": "Auth token has no DNS permits"
}

Primary DNS API v2

Authentication and authorisation

API overview

Terminology: zones vs domains

Selecting records

Interacting with records

Input and output formats

Updating records

Transactions

ANAME records

Fields

Filtering

Combining filters

Boolean query parameters

Base URL

Endpoints

get /record-types

Responses

Example

get /zones

Responses

Example

get /zones/{zone}/records

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

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

Parameters

Responses

Example

Example

post /zones/{zone}/records

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

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

Parameters

Request Body JSON

Example

Request Body Form

Request Body Zone

Example

Responses

Example

put /zones/{zone}/records

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

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

Parameters

Request Body JSON

Example

Request Body Form

Request Body Zone

Example

Responses

Example

delete /zones/{zone}/records

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

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

Parameters

Responses

Example

put /dynamic/{host}

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

Parameters

Request Body Form

Responses

Example

Parameter groups

Common query parameters

Record filters

Property groups

Additional fields

Common errors

Example

Example

Example

Support Index

Page contents

Mythic Beasts

About Us

Contact Us