Zone Record API
- Zone record attributes
- Record Regions
- List zone records
- Create a zone record
- Retrieve a zone record
- Update a zone record
- Delete a zone record
- Check zone record distribution
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"
}