Domain 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

{
    "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

{
    "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

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

Bad request

application/json

{
    "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

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

Bad request

application/json

{
    "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

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

Bad request

application/json

{
    "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

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

Bad request

application/json

{
    "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

{
    "name": "example.com",
    "lock": true
}
400

Bad request

application/json

{
    "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

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

Bad request

application/json

{
    "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

{
    "name": "example.com",
    "dns": true
}
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

{
    "name": "example.com",
    "dnssec": true
}
403 Not authorised

Common errors

CodeDescription
403

Not authorised to access domain or domain does not exist.

application/json

{
    "error": "Not authorized"
}