Domains API

OpenAPI YAML

This API enables management of domains registered with Mythic Beasts.

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.

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.

API Keys can be limited to accessing individual domains, or all domains on your account. API Keys can be read-only, or given access to make changes to your domains. The permissions that can be added to a key currently are:

  • NS - API Key can update the nameservers for the domain(s)
  • DNSSEC - API Key can update the DS records for the domain(s)

Granting either of the above permissions to an API Key will also give the key the ability enable and disable domain locking, if the domain type supports it.

The base URL for this service is:

  • https://api.mythic-beasts.com/beta

The endpoints listed below should be appended to the above URL.

Endpoints

get /domains

https://api.mythic-beasts.com/beta/domains

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

If the key has any permission that is not restricted by domain, it will list all zones on the customer account.

Responses

CodeDescription
200

List of domains

application/json

NameDescription
domains array

List of domains
Example
{
    "domains": [
        "example.com",
        "example2.com"
    ]
}
403 Not authorised

get /domains/{domain}

https://api.mythic-beasts.com/beta/domains/{domain}

Returns information about the specified domain.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

Domain information.

Status is one of the following values:

  • registered - domain is registered with Mythic Beasts.
  • dns_only - domain is not registered with Mythic Beasts, but DNS service can be enabled (also known as "3rd Party Domain").
  • expired_grace_period - domain registration has expired, but can still be renewed normally.
  • expired - domain has expired. It may be possible to renew via support.
  • suspended - domain registration is suspended.
  • awaiting_transfer - UK domain has been registered for transfer in, but has not yet been re-tagged
  • in_transfer - transfer is in progress (non-UK)

expiry is absent for dns_only, awaiting_transfer and in_transfer.

locked and dnssec will only be shown for registered domains and for supported domain types.

application/json

NameDescription
domain string

Name of domain
status string

Status of the domain
expiry string

Expiry date of domain. Absent if status is not
dns boolean

Whether DNS service is active for this domain
dnssec boolean

Whether managed DNSSEC is active for this domain
locked boolean

Whether domain is locked. Absent if domain locking is not available on this domain type.
Example
{
    "domain": "example.com",
    "status": "registered",
    "expiry": "2022-01-01",
    "dns": true,
    "dnssec": true,
    "locked": true
}
403 Not authorised

get /domains/{domain}/nameservers

https://api.mythic-beasts.com/beta/domains/{domain}/nameservers

Returns a list of nameservers for the domain. Each nameserver will have a name, and optionally an IPv4 and/or IPv6 address.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

Nameserver information.

application/json

NameDescription
domain string

Name of domain
nameservers array

List of nameservers
name string

Nameserver hostname
ipv4 string

Nameserver IPv4 address
ipv6 string

Nameserver IPv6 address
Example
{
    "domain": "example.com",
    "nameservers": [
        {
            "name": "ns1.example.com",
            "ipv4": "45.33.127.156",
            "ipv6": "2600:3c00:e000:19::1"
        }
    ]
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not supported (domain status: in_transfer)"
}
403 Not authorised

put /domains/{domain}/nameservers

https://api.mythic-beasts.com/beta/domains/{domain}/nameservers

Update the nameservers for a domain. Accepts a list of between 2 and 10 nameservers, which will replace the current nameservers. If the hostname of a nameserver is within the domain for which you are setting nameservers, you should provide an IPv4 and/or IPv6 address which will be used to create the necessary glue records.

This action requires an API Key with the NS permission.

Parameters

NameLocationDescription
domain string path

The domain name

Request Body JSON

NameDescription
nameservers array

(Required) List of nameservers
name string

(Required) Hostname of nameservers
ipv4 number

(Optional) IPv4 address for nameservers. Will be ignored unless needed for glue records (nameserver hostname is within the current domain name).
ipv6 string

(Optional) IPv6 address for nameservers. Will be ignored unless needed for glue records (nameserver hostname is within the current domain name).
Example

application/json

{
    "nameservers": [
        {
            "name": "ns1.example.com",
            "ipv4": "45.33.127.156",
            "ipv6": "2600:3c00:e000:19::1"
        }
    ]
}

Responses

CodeDescription
200

Success

application/json

NameDescription
domain string

Name of domain
message string

Response message
Example
{
    "domain": "example.com",
    "message": "Nameservers updated"
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Missing parameter 'nameservers'"
}
403 Not authorised

get /domains/{domain}/ds

https://api.mythic-beasts.com/beta/domains/{domain}/ds

Returns a list of the domain's DS records.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

DS records

application/json

NameDescription
domain string

Name of domain
records array

List of DS records
key_tag integer

Key tag field
algorithm integer

Algorithm field
digest_type integer

Digest type field
digest string

Digest field
Example
{
    "domain": "example.com",
    "records": [
        {
            "key_tag": 7962,
            "algorithm": 10,
            "digest_type": 2,
            "digest": "608EEB2F566855F6590F6EFF9C3EF96E8B7C07A0F1443BA95077A3CDA383F8D8"
        }
    ]
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not supported (domain status: in_transfer)"
}
403 Not authorised

put /domains/{domain}/ds

https://api.mythic-beasts.com/beta/domains/{domain}/ds

Set the DS records for the domain. This will replace all current DS records for the domain with those provided in the request.

This action requires an API Key with the DNSSEC permission.

Parameters

NameLocationDescription
domain string path

The domain name

Request Body JSON

NameDescription
records array

(Required) List of DS records
key_tag integer

(Required) Key tag field
algorithm integer

(Required) Algorithm field
digest_type integer

(Required) Digest type field
digest string

(Required) Digest field
Example

application/json

{
    "records": [
        {
            "key_tag": 7962,
            "algorithm": 10,
            "digest_type": 2,
            "digest": "608EEB2F566855F6590F6EFF9C3EF96E8B7C07A0F1443BA95077A3CDA383F8D8"
        }
    ]
}

Responses

CodeDescription
200

Success

application/json

NameDescription
domain string

Name of domain
message string

Response message
Example
{
    "domain": "example.com",
    "message": "2 record(s) set"
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Missing parameter 'records'"
}
403 Not authorised

get /domains/{domain}/lock

https://api.mythic-beasts.com/beta/domains/{domain}/lock

Gets the domain lock state (prevents modifications to do the domain if enabled).

Domain locking is not supported on all domain types. This endpoint will return a 400 status if domain locking is not supported.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

Domain lock state

application/json

NameDescription
domain string

Name of domain
lock boolean

Lock state
Example
{
    "domain": "example.com",
    "lock": true
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Locking is not supported on this domain type"
}
403 Not authorised

put /domains/{domain}/lock

https://api.mythic-beasts.com/beta/domains/{domain}/lock

Sets the domain lock state (prevents modifications to do the domain if enabled).

Domain locking is not supported on all domain types. This endpoint will return a 400 status if domain locking is not supported.

This action requires an API Key with either the DNSSEC or NS permission.

Parameters

NameLocationDescription
domain string path

The domain name

Request Body JSON

NameDescription
lock boolean

(Required) Domain lock state
Example

application/json

{
    "lock": true
}

Responses

CodeDescription
200

Nameserver information.

application/json

NameDescription
domain string

Name of domain
nameservers array

List of nameservers
name string

Nameserver hostname
ipv4 string

Nameserver IPv4 address
ipv6 string

Nameserver IPv6 address
Example
{
    "domain": "example.com",
    "nameservers": [
        {
            "name": "ns1.example.com",
            "ipv4": "45.33.127.156",
            "ipv6": "2600:3c00:e000:19::1"
        }
    ]
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Missing parameter 'records'"
}
403 Not authorised

get /domains/{domain}/dns

https://api.mythic-beasts.com/beta/domains/{domain}/dns

Indicates whether DNS service is currently active for this domain.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

DNS service state

application/json

NameDescription
domain string

Name of domain
dns boolean

DNS service state
Example
{
    "domain": "example.com",
    "dns": true
}
403 Not authorised

put /domains/{domain}/dns

https://api.mythic-beasts.com/beta/domains/{domain}/dns

Enable or disable DNS hosting for this domain.

DNS hosting is unsupported on domains that are already configured for secondary DNS hosting.

This action requires an API Key with the NS permission.

Parameters

NameLocationDescription
domain string path

The domain name

Request Body JSON

NameDescription
dns boolean

(Required) DNS service status
Example

application/json

{
    "dns": true
}

Responses

CodeDescription
200

DNS service state

application/json

NameDescription
domain string

Name of domain
dns boolean

DNS service state
Example
{
    "domain": "example.com",
    "dns": true
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "DNS hosting cannot be enabled for this domain"
}
403 Not authorised

get /domains/{domain}/dnssec

https://api.mythic-beasts.com/beta/domains/{domain}/dnssec

Gets the status of managed DNSSEC service on this domain. Managed DNSSEC is available on domains registered with Mythic Beasts, and automatically sets and updates DS keys for the domain, as well as providing signed DNS responses.

Parameters

NameLocationDescription
domain string path

The domain name

Responses

CodeDescription
200

Managed DNSSEC state

application/json

NameDescription
domain string

Name of domain
dnssec boolean

Managed DNSSEC service state
Example
{
    "domain": "example.com",
    "dnssec": true
}
403 Not authorised

put /domains/{domain}/dnssec

https://api.mythic-beasts.com/beta/domains/{domain}/dnssec

Enable managed DNSSEC for this domain.

Please note that DNSSEC cannot currently be disabled automatically. You will need to contact support if you wish to disable it.

This action requires an API Key with the DNSSEC permission.

Parameters

NameLocationDescription
domain string path

The domain name

Request Body JSON

NameDescription
dnssec boolean

(Required) DNSSEC status
Example

application/json

{
    "dnssec": true
}

Responses

CodeDescription
200

Managed DNSSEC state

application/json

NameDescription
domain string

Name of domain
dnssec boolean

Managed DNSSEC service state
Example
{
    "domain": "example.com",
    "dnssec": true
}
400

Bad request

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Managed DNSSEC is not supported for this domain"
}
403 Not authorised

Common errors

CodeDescription
403

Not authorised to access domain or domain does not exist.

application/json

NameDescription
error string

A description of the error
Example
{
    "error": "Not authorized"
}

Support Index

Page contents