Zone Record API

Zone Record Regions

This Zone Record Regions is a feature that is only available to the following new plans: Professional and Business.

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

We currently have 5 points of presence:

Code Region
SV1 California, US
ORD Illinois, US
IAD Virginia, US
AMS Amsterdam, NL
TKO Tokyo, JP

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 records for a zone

GET /:account/zones/:zone/records

Parameters

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

Example

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

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
  }
}

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

Example

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

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.

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. 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.

Get 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 of any of them.

Name Type Description
name string  
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.