components:
  securitySchemes:
    Bearer: {in: header, name: Authorization, type: apiKey}
info:
  contact: {email: support@mythic-beasts.com}
  description: "\nThis API enables management of domains registered with Mythic Beasts.\n\
    \n## Authentication and authorisation\n\nThis API uses our [auth service](auth).\
    \  Credentials for using this API can\nbe obtained from the [API Keys](https://www.mythic-beasts.com/customer/api-users)\
    \ section of the\ncontrol panel.  \n\nAuthentication for the DNS API can be done\
    \ using a \"Bearer token\".  In\nthis, you provide your credentials to the [auth\
    \ service](auth) which will\nreturn a token which can be used in subsequent requests.\
    \  See the\n[documentation for the auth service](auth) for more details.\n\nAPI\
    \ Keys can be limited to accessing individual domains, or\nall domains on your\
    \ account.  API Keys can be read-only, or given access to\nmake changes to your\
    \ domains.  The permissions that can be added to a key currently are:\n\n  * **NS**\
    \ - API Key can update the nameservers for the domain(s)\n  * **DNSSEC** - API\
    \ Key can update the DS records for the domain(s)\n\nGranting either of the above\
    \ permissions to an API Key will also give the\nkey the ability enable and disable\
    \ domain locking, if the domain type\nsupports it.\n\nThe base URL for this service\
    \ is:\n\n*  **https://api.mythic-beasts.com/beta**\n\nThe endpoints listed below\
    \ should be appended to the above URL.\n\n\n"
  termsOfService: https://www.mythic-beasts.com/article/terms
  title: Domain Management API
  version: 0.1.0
openapi: 3.0.0
paths:
  /domains:
    get:
      description: '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.


        '
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  domains: [example.com, example2.com]
                properties:
                  domains:
                    description: List of domains
                    items: {description: Domain name, type: string}
                    type: array
                type: object
          description: 'List of domains


            '
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: List domains
      tags: [Domains]
  /domains/{domain}:
    get:
      description: 'Returns information about the specified domain.


        '
      parameters:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  dns: {description: Whether DNS service is active for this domain,
                    example: true, type: boolean}
                  dnssec: {description: Whether managed DNSSEC is active for this
                      domain, example: true, type: boolean}
                  domain: {description: Name of domain, example: example.com, type: string}
                  expiry: {description: Expiry date of domain.  Absent if status is
                      not, example: '2022-01-01', type: string}
                  locked: {description: Whether domain is locked.  Absent if domain
                      locking is not available on this domain type., example: true,
                    type: boolean}
                  status: {description: Status of the domain, example: registered,
                    type: string}
                type: object
          description: '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.


            '
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get domain information
      tags: [Domains]
  /domains/{domain}/dns:
    get:
      description: '

        Indicates whether DNS service is currently active for this domain.


        '
      parameters:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                example: {dns: true, domain: example.com}
                properties:
                  dns: {description: DNS service state, example: true, type: boolean}
                  domain: {description: Name of domain, example: example.com, type: string}
                type: object
          description: 'DNS service state


            '
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get DNS status
      tags: [Domains]
    put:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              example: {dns: true}
              properties:
                dns: {description: DNS service status, required: true, type: boolean}
      responses:
        '200':
          content:
            application/json:
              schema:
                example: {dns: true, domain: example.com}
                properties:
                  dns: {description: DNS service state, example: true, type: boolean}
                  domain: {description: Name of domain, example: example.com, type: string}
                type: object
          description: '

            DNS service state


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: DNS hosting
                      cannot be enabled for this domain, type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Set DNS status
      tags: [Domains]
  /domains/{domain}/dnssec:
    get:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                example: {dnssec: true, domain: example.com}
                properties:
                  dnssec: {description: Managed DNSSEC service state, example: true,
                    type: boolean}
                  domain: {description: Name of domain, example: example.com, type: string}
                type: object
          description: 'Managed DNSSEC state


            '
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get managed DNSSEC status
      tags: [Domains]
    put:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              example: {dnssec: true}
              properties:
                dnssec: {description: DNSSEC status, required: true, type: boolean}
      responses:
        '200':
          content:
            application/json:
              schema:
                example: {dnssec: true, domain: example.com}
                properties:
                  dnssec: {description: Managed DNSSEC service state, example: true,
                    type: boolean}
                  domain: {description: Name of domain, example: example.com, type: string}
                type: object
          description: '

            Managed DNSSEC state


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Managed
                      DNSSEC is not supported for this domain, type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Set managed DNSSEC status
      tags: [Domains]
  /domains/{domain}/ds:
    get:
      description: '

        Returns a list of the domain''s DS records.


        '
      parameters:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  domain: example.com
                  records:
                  - {algorithm: 10, digest: 608EEB2F566855F6590F6EFF9C3EF96E8B7C07A0F1443BA95077A3CDA383F8D8,
                    digest_type: 2, key_tag: 7962}
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  records:
                    description: List of DS records
                    items:
                      properties:
                        algorithm: {description: Algorithm field, type: integer}
                        digest: {description: Digest field, type: string}
                        digest_type: {description: Digest type field, type: integer}
                        key_tag: {description: Key tag field, type: integer}
                      type: object
                    type: array
                type: object
          description: 'DS records


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: 'Not supported
                      (domain status: in_transfer)', type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get DS records
      tags: [Domains]
    put:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              example:
                records:
                - {algorithm: 10, digest: 608EEB2F566855F6590F6EFF9C3EF96E8B7C07A0F1443BA95077A3CDA383F8D8,
                  digest_type: 2, key_tag: 7962}
              properties:
                records:
                  description: List of DS records
                  items:
                    properties:
                      algorithm: {description: Algorithm field, required: true, type: integer}
                      digest: {description: Digest field, required: true, type: string}
                      digest_type: {description: Digest type field, required: true,
                        type: integer}
                      key_tag: {description: Key tag field, required: true, type: integer}
                    type: object
                  required: true
                  type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  message: {description: Response message, example: 2 record(s) set,
                    type: string}
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Missing
                      parameter 'records', type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Set DS records
      tags: [Domains]
  /domains/{domain}/lock:
    get:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                example: {domain: example.com, lock: true}
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  lock: {description: Lock state, example: true, type: boolean}
                type: object
          description: 'Domain lock state


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Locking
                      is not supported on this domain type, type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get domain lock state
      tags: [Domains]
    put:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              example: {lock: true}
              properties:
                lock: {description: Domain lock state, required: true, type: boolean}
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  domain: example.com
                  nameservers:
                  - {ipv4: 45.33.127.156, ipv6: '2600:3c00:e000:19::1', name: ns1.example.com}
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  nameservers:
                    description: List of nameservers
                    items:
                      description: Nameserver details
                      properties:
                        ipv4: {description: Nameserver IPv4 address, type: string}
                        ipv6: {description: Nameserver IPv6 address, type: string}
                        name: {description: Nameserver hostname, type: string}
                      type: object
                    type: array
                type: object
          description: '

            Nameserver information.


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Missing
                      parameter 'records', type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Set domain lock state
      tags: [Domains]
  /domains/{domain}/nameservers:
    get:
      description: '

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


        '
      parameters:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      responses:
        '200':
          content:
            application/json:
              schema:
                example:
                  domain: example.com
                  nameservers:
                  - {ipv4: 45.33.127.156, ipv6: '2600:3c00:e000:19::1', name: ns1.example.com}
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  nameservers:
                    description: List of nameservers
                    items:
                      description: Nameserver details
                      properties:
                        ipv4: {description: Nameserver IPv4 address, type: string}
                        ipv6: {description: Nameserver IPv6 address, type: string}
                        name: {description: Nameserver hostname, type: string}
                      type: object
                    type: array
                type: object
          description: 'Nameserver information.


            '
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: 'Not supported
                      (domain status: in_transfer)', type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Get nameservers
      tags: [Domains]
    put:
      description: '

        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:
      - description: The domain name
        in: path
        name: domain
        required: true
        schema: {type: string}
      requestBody:
        content:
          application/json:
            schema:
              example:
                nameservers:
                - {ipv4: 45.33.127.156, ipv6: '2600:3c00:e000:19::1', name: ns1.example.com}
              properties:
                nameservers:
                  description: List of nameservers
                  items:
                    properties:
                      ipv4: {description: IPv4 address for nameservers.  Will be ignored
                          unless needed for glue records (nameserver hostname is within
                          the current domain name)., example: 45.33.127.156, type: number}
                      ipv6: {description: IPv6 address for nameservers.  Will be ignored
                          unless needed for glue records (nameserver hostname is within
                          the current domain name)., example: '2600:3c00:e000:19::1',
                        type: string}
                      name: {description: Hostname of nameservers, example: ns1.example.com,
                        required: true, type: string}
                    required: [name]
                    type: object
                  required: true
                  type: array
              required: [nameservers]
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  domain: {description: Name of domain, example: example.com, type: string}
                  message: {description: Response message, example: Nameservers updated,
                    type: string}
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Missing
                      parameter 'nameservers', type: string}
                type: object
          description: Bad request
        '403':
          content:
            application/json:
              schema:
                properties:
                  error: {description: A description of the error, example: Not authorized,
                    type: string}
                type: object
          description: Not authorised to access domain or domain does not exist.
          x-mythic-error-summary: Not authorised
      security:
      - Bearer: []
      summary: Set nameservers
      tags: [Domains]
servers:
- {url: 'https://api.mythic-beasts.com/beta'}
tags:
- {description: Domain management, name: Domains}
