API Reference

Contents

Overview

The DNS Data API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

Authenticate your account by including your API key in requests. If your account has access to the API, then you can generate an API key under the "API" tab of the Account page.

Note that API access is a paid feature so you'll need a paid account to continue..

Authentication is done by including your API key in an HTTP Authorization header.

Authorization: Bearer YOUR.API.KEY

All API requests must be made over HTTPS. API requests without authentication will fail.

Errors

We use conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers (these are rare).

Rate Limits

Each API endpoint has a rate limit. If an account sends more than the allowed number of requests in a given time period, the API will respond with an HTTP 429 error code. The response will include a Retry-After header that contains the number of seconds to wait before trying again.

API Resources

DNS Domains

Domain objects represent a Domain returned from DNS.

The attributes of the Domain object are documented below.

name
The name of the Domain.
resource_records
A list of Resource Records associated with the Domain.

List Domains by Prefix

Returns a list of Domains that have a given name prefix.

Request Options
cursor

Used to paginate through API results. The first request to this endpoint will include a cursor attribute in the response if additonal records are available. Send that value in the cursor request option of the next request to fetch the next batch of records. Continue in this fashion until there are no more records to retrieve.

fields

A comma-separated list of fields to include in the response. All default fields are returned if left blank. If you only need a subset of fields in the response, it is recommended to use this request parameter since it can have a significant impact on response time.

limit

The maximum number of change sets (grouped by timestamp) to returned. By default, all change sets are returned.

Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/domains/mail./prefix?limit=5'

Example Response

{
  "domains": [
    {
      "name": "mail.*.2-your-success.com",
      "resource_records": [
        {
          "name": "mail.*.2-your-success.com.",
          "type": "NS",
          "value": "ns2.mywahosting.com."
        },
        {
          "name": "mail.*.2-your-success.com.",
          "type": "NS",
          "value": "ns1.mywahosting.com."
        },
        {
          "name": "mail.*.2-your-success.com.",
          "type": "MX",
          "value": "1\tmail.mail.*.2-your-success.com."
        },
        {
          "name": "mail.*.2-your-success.com.",
          "type": "TXT",
          "value": "v=spf1 include:spf.mywahosting.com -all"
        }
      ]
    },
    {
      "name": "mail.*.3xweekly.com",
      "resource_records": [
        {
          "name": "mail.*.3xweekly.com.",
          "type": "NS",
          "value": "ns2.mywahosting.com."
        },
        {
          "name": "mail.*.3xweekly.com.",
          "type": "NS",
          "value": "ns1.mywahosting.com."
        },
        {
          "name": "mail.*.3xweekly.com.",
          "type": "MX",
          "value": "1\tmail.mail.*.3xweekly.com."
        },
        {
          "name": "mail.*.3xweekly.com.",
          "type": "TXT",
          "value": "v=spf1 include:spf.mywahosting.com -all"
        }
      ]
    },
    {
      "name": "mail.*.40somethings.com",
      "resource_records": [
        {
          "name": "mail.*.40somethings.com.",
          "type": "NS",
          "value": "ns1.mywahosting.com."
        },
        {
          "name": "mail.*.40somethings.com.",
          "type": "NS",
          "value": "ns2.mywahosting.com."
        },
        {
          "name": "mail.*.40somethings.com.",
          "type": "MX",
          "value": "1\tmail.mail.*.40somethings.com."
        },
        {
          "name": "mail.*.40somethings.com.",
          "type": "TXT",
          "value": "v=spf1 include:spf.mywahosting.com -all"
        }
      ]
    },
    {
      "name": "mail.*.accelerants.net",
      "resource_records": [
        {
          "name": "mail.*.accelerants.net.",
          "type": "NS",
          "value": "ns1.mywahosting.com."
        },
        {
          "name": "mail.*.accelerants.net.",
          "type": "NS",
          "value": "ns2.mywahosting.com."
        },
        {
          "name": "mail.*.accelerants.net.",
          "type": "MX",
          "value": "1\tmail.mail.*.accelerants.net."
        },
        {
          "name": "mail.*.accelerants.net.",
          "type": "TXT",
          "value": "v=spf1 include:spf.mywahosting.com -all"
        }
      ]
    },
    {
      "name": "mail.*.accessibilityworld.com",
      "resource_records": [
        {
          "name": "mail.*.accessibilityworld.com.",
          "type": "NS",
          "value": "ns2.mywahosting.com."
        },
        {
          "name": "mail.*.accessibilityworld.com.",
          "type": "NS",
          "value": "ns1.mywahosting.com."
        },
        {
          "name": "mail.*.accessibilityworld.com.",
          "type": "MX",
          "value": "1\tmail.mail.*.accessibilityworld.com."
        },
        {
          "name": "mail.*.accessibilityworld.com.",
          "type": "TXT",
          "value": "v=spf1 include:spf.mywahosting.com -all"
        }
      ]
    }
  ]
}

DNS Resource Records

Resource Record objects represent a Resource Record returned from DNS.

The attributes of the Resource Record object are documented below.

name
The name of the Resource Record.
value
The value of the Resource Record.
type
The type of the Resource Record (e.g., A or CNAME).

List Resource Records for Domain

Returns a list of Resource Record associated with a domain name.

Request Options
fields

A comma-separated list of fields to include in the response. All default fields are returned if left blank. If you only need a subset of fields in the response, it is recommended to use this request parameter since it can have a significant impact on response time.

Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/resource-records/domain/amazon.com'

Example Response

{
  "resource_records": [
    {
      "name": "amazon.com.",
      "type": "A",
      "value": "52.94.236.248"
    },
    {
      "name": "amazon.com.",
      "type": "A",
      "value": "54.239.28.85"
    },
    {
      "name": "amazon.com.",
      "type": "A",
      "value": "205.251.242.103"
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns2.amzndns.co.uk."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns2.amzndns.org."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns2.amzndns.com."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns1.amzndns.net."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns1.amzndns.co.uk."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns2.amzndns.net."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns1.amzndns.org."
    },
    {
      "name": "amazon.com.",
      "type": "NS",
      "value": "ns1.amzndns.com."
    },
    {
      "name": "amazon.com.",
      "type": "MX",
      "value": "5\tamazon-smtp.amazon.com."
    }
  ]
}

List Resource Records Changes for Domain

Returns a history of Resource Record changes associated with a domain name. Results are grouped by timestamp and are returned with the oldest changes first.

Note:

  • Change log history goes back to August 2022. Changes prior to that date are not available.
  • Each set of changes (grouped by timestamp) includes all Resource Records known at the time of change. Use the type request parameter to retrieve changes for a specific Resource Record type.
Request Options
limit

The maximum number of change sets (grouped by timestamp) to returned. By default, all change sets are returned.

sort

Changes the sort order. Prefix fields with a minus sign (-) to denote descending sort order. Default: ts

Valid values are:

  • ts (which returns change logs from oldest to newest)
  • -ts (which returns change logs from newest to oldest)
type

Filter the change logs to only include values for the given Resource Record type. Multiple types can be separated by comma.

Valid values are:

  • A
  • CNAME
  • DNAME
  • MX
  • NS
  • TXT
  • SPF
Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/resource-records/domain/storeleads.com/changes'

Example Response

{
  "changes": [
    {
      "ts": "2022-08-16T00:00:00Z",
      "resource_records": [
        {
          "type": "A",
          "values": [
            "75.2.70.75",
            "99.83.190.102"
          ]
        },
        {
          "type": "NS",
          "values": [
            "ns31.domaincontrol.com.",
            "ns32.domaincontrol.com."
          ]
        }
      ]
    },
    {
      "ts": "2023-05-10T00:00:00Z",
      "resource_records": [
        {
          "type": "A",
          "values": [
            "35.226.202.80"
          ]
        },
        {
          "type": "NS",
          "values": [
            "ns-cloud-d1.googledomains.com.",
            "ns-cloud-d2.googledomains.com.",
            "ns-cloud-d3.googledomains.com.",
            "ns-cloud-d4.googledomains.com."
          ]
        }
      ]
    }
  ]
}

List Resource Records by Type

Returns a list of Resource Record associated with a given type.

At present, we are collecting the following types: A, CNAME, MX, NS, TXT and SPF. Please contact us if you'd like data for a different resource record type.

Request Options
cursor

Used to paginate through API results. The first request to this endpoint will include a cursor attribute in the response if additonal records are available. Send that value in the cursor request option of the next request to fetch the next batch of records. Continue in this fashion until there are no more records to retrieve.

fields

A comma-separated list of fields to include in the response. All default fields are returned if left blank. If you only need a subset of fields in the response, it is recommended to use this request parameter since it can have a significant impact on response time.

limit

Limit configures the number of records returned per request. The default and maxium limits depend on your pricing plan.

Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/resource-records/type/A?limit=5'

Example Response

{
  "cursor": "BQABAEAQAAAAqPqixQg=",
  "resource_records": [
    {
      "name": "facebook.com.",
      "type": "A",
      "value": "157.240.254.35"
    },
    {
      "name": "fonts.googleapis.com.",
      "type": "A",
      "value": "142.250.191.138"
    },
    {
      "name": "google.com.",
      "type": "A",
      "value": "142.250.191.174"
    },
    {
      "name": "www.google.com.",
      "type": "A",
      "value": "142.251.161.103"
    },
    {
      "name": "www.google.com.",
      "type": "A",
      "value": "142.251.161.105"
    }
  ]
}

List Resource Records by Type and Value

Returns a list of Resource Record associated with a given type and value.

At present, we are collecting the following types: A, CNAME, MX, NS, TXT and SPF. Please contact us if you'd like data for a different resource record type.

Request Options
cursor

Used to paginate through API results. The first request to this endpoint will include a cursor attribute in the response if additonal records are available. Send that value in the cursor request option of the next request to fetch the next batch of records. Continue in this fashion until there are no more records to retrieve.

fields

A comma-separated list of fields to include in the response. All default fields are returned if left blank. If you only need a subset of fields in the response, it is recommended to use this request parameter since it can have a significant impact on response time.

limit

Limit configures the number of records returned per request. The default and maxium limits depend on your pricing plan.

Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/resource-records/type/CNAME/shops.myshopify.com?limit=5'

Example Response

{
  "cursor": "BgAFAHNob3BpZnkubXlzaG9waWZ5LmNvbQBLBMSIAPippIAK",
  "resource_records": [
    {
      "name": "www.readingwithrik.com.",
      "type": "CNAME",
      "value": "shopify.myshopify.com."
    },
    {
      "name": "www.thomsweeney.com.",
      "type": "CNAME",
      "value": "shopify.myshopify.com."
    },
    {
      "name": "www.rareteacellar.com.",
      "type": "CNAME",
      "value": "shopify.myshopify.com."
    },
    {
      "name": "www.axis-y.com.",
      "type": "CNAME",
      "value": "shopify.myshopify.com."
    },
    {
      "name": "www.mobovida.com.",
      "type": "CNAME",
      "value": "shopify.myshopify.com."
    }
  ]
}

Notes:

  • When matching values for MX records, we automatically strip the MX priority from the value to support direct matches on the host.

List Resource Records by Type and Value Prefix

Returns a list of Resource Record associated with a given type and value prefix. This is useful for finding all Resource Records that start with a given prefix.

At present, we are collecting the following types: A, CNAME, MX, NS, TXT and SPF. Please contact us if you'd like data for a different resource record type.

Note: when matching values for MX records, we automatically strip the MX priority from the value to support direct matches on the host.

Request Options
cursor

Used to paginate through API results. The first request to this endpoint will include a cursor attribute in the response if additonal records are available. Send that value in the cursor request option of the next request to fetch the next batch of records. Continue in this fashion until there are no more records to retrieve.

fields

A comma-separated list of fields to include in the response. All default fields are returned if left blank. If you only need a subset of fields in the response, it is recommended to use this request parameter since it can have a significant impact on response time.

limit

Limit configures the number of records returned per request. The default and maxium limits depend on your pricing plan.

Example Request

$ curl -H 'Authorization: Bearer YOUR.API.KEY' 'https://dnsdata.app/json/api/v1/resource-records/type/CNAME/mail./prefix?limit=5'

Example Response

{
  "cursor": "BgAFAG1haWwuMC1idWcuY29tAFKaLoQAkMqqmwM=",
  "resource_records": [
    {
      "name": "imap.0-52355866484.store.",
      "type": "CNAME",
      "value": "mail.0-52355866484.store."
    },
    {
      "name": "smtp.0-52355866484.store.",
      "type": "CNAME",
      "value": "mail.0-52355866484.store."
    },
    {
      "name": "pop.0-52355866484.store.",
      "type": "CNAME",
      "value": "mail.0-52355866484.store."
    },
    {
      "name": "smtp.0-bug.com.",
      "type": "CNAME",
      "value": "mail.0-bug.com."
    },
    {
      "name": "imap.0-bug.com.",
      "type": "CNAME",
      "value": "mail.0-bug.com."
    }
  ]
}

Questions

If you have any questions or feature suggestions, please contact us.