Zone Record API

Zone record attributes

Please refer to the definition of the ZoneRecord data type in our OpenAPI documentation.

Record Regions

The zone record regions is a feature that is only available to the following new plans: Professional and Business. If the feature is not enabled, you will receive an HTTP 412 response code.

Zone Record Regions lets you select geographical regions where you want a record to appear.

We currently have 8 points of presence:

Code Region
SV1 California, US
ORD Illinois, US
IAD Virginia, US
AMS Amsterdam, NL
TKO Tokyo, JP
SYD Sydney, AU
CDG Paris, FR
FRA Frankfurt, DE

When creating/updating a record, you can optionally select one or more regions. If you don’t select any, the record will appear in all of them (global).

List zone records

GET /:account/zones/:zone/records

Parameters

Name Type Description
:account integer The account id
:zone string The zone name

Filters

Name Description
:name_like Only include records containing given string
:name Only include records with name equal to given string
:type Only include records with record type equal to given string

Sorting

For general information about sorting, please refer to the main guide.

Name Description
id Sort records by ID
name Sort records by name (alphabetical order)
content Sort records by content
type Sort records by type

The default sorting policy is by ascending id.

Examples

List records for the zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records

List records for the zone example.com with TXT zone records, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records?type=TXT

Response

Responds with HTTP 200.

{
  "data": [
    {
      "id": 1,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns1.dnsimple.com admin.dnsimple.com 1458642070 86400 7200 604800 300",
      "ttl": 3600,
      "priority": null,
      "type": "SOA",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-10-05T09:26:38Z"
    },
    {
      "id": 69061,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns1.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 2,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns2.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 3,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns3.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 4,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns4.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 5,
    "total_pages": 1
  }
}

Create a zone record

POST /:account/zones/:zone/records

Parameters

Name Type Description
:account integer The account id
:zone string The zone name

Example

Create a record for the zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records

Input

Name Type Description
name string Required. The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
type string Required.
content string Required.
ttl integer  
priority integer  
regions array Optional set of regions
Example
{
  "name": "",
  "type": "MX",
  "content": "mxa.example.com",
  "ttl": 600,
  "priority": 10,
  "regions": ["SV1", "IAD"]
}

Response

Responds with HTTP 201 on success.

{
  "data": {
    "id": 1,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "www",
    "content": "127.0.0.1",
    "ttl": 600,
    "priority": null,
    "type": "A",
    "system_record": false,
    "regions": [
      "global"
    ],
    "created_at": "2016-01-07T17:45:13Z",
    "updated_at": "2016-01-07T17:45:13Z"
  }
}

Responds with HTTP 400 if bad request.

Responds with HTTP 400 if the validation fails.

Retrieve a zone record

GET /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Get the record 5 for the zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Response

{
  "data": {
    "id": 5,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "",
    "content": "mxa.example.com",
    "ttl": 600,
    "priority": 10,
    "type": "MX",
    "regions": [
      "SV1",
      "IAD"
    ],
    "system_record": false,
    "created_at": "2016-10-05T09:51:35Z",
    "updated_at": "2016-10-05T09:51:35Z"
  }
}

Update a zone record

PATCH /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Update the record with ID 5 for zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Input

The following fields are updateable. You can pass zero or any of them.

Name Type Description
name string The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
content string  
ttl integer  
priority integer  
regions array Optional set of regions
Example
{
  "content": "mxb.example.com",
  "ttl": 3600,
  "priority": 20
  "regions": ["global"]
}

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 5,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "",
    "content": "mxb.example.com",
    "ttl": 3600,
    "priority": 20,
    "type": "MX",
    "regions": [
      "global"
    ],
    "system_record": false,
    "created_at": "2016-10-05T09:51:35Z",
    "updated_at": "2016-10-05T09:51:35Z"
  }
}

Responds with HTTP 400 if bad request.

Responds with HTTP 400 if the validation fails.

Delete a zone record

DELETE /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Delete the record with ID 5 for zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Response

Responds with HTTP 204 on success.

Check zone record distribution

Checks if a zone change is fully distributed to all our nameservers across the globe.

GET /:account/zones/:zone/records/:record/distribution

This feature is not available for testing in our Sandbox environment.

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Check the zone record distribution for example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5/distribution

Response

Responds with HTTP 200 when the zone record is fully distributed.

{
  "data": {
    "distributed": true
  }
}

Responds with HTTP 200 when the zone record is not distributed.

{
  "data": {
    "distributed": false
  }
}

Responds with HTTP 504 when the server failed to perform the check.

{
  "message": "Could not query zone, connection timed out"
}