Zones API

Zone attributes

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

List zones

Lists the zones in the account.

GET /:account/zones

Parameters

Name Type Description
:account integer The account id

Filters

Name Description
:name_like Only include zones containing given string

Sorting

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

Name Description
id Sort zones by ID
name Sort zones by name (alphabetical order)

The default sorting policy is by ascending name.

Examples

List all zones in the account 1010:

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

List all zones in the account 1010 that have name matching "example":

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

Response

Responds with HTTP 200 on success.

{
  "data": [
    {
      "id": 1,
      "account_id": 1010,
      "name": "example-alpha.com",
      "reverse": false,
      "secondary": false,
      "last_transferred_at": null,
      "active": true,
      "created_at": "2015-04-23T07:40:03Z",
      "updated_at": "2015-04-23T07:40:03Z"
    },
    {
      "id": 2,
      "account_id": 1010,
      "name": "example-beta.com",
      "reverse": false,
      "secondary": false,
      "last_transferred_at": null,
      "active": true,
      "created_at": "2015-04-23T07:40:03Z",
      "updated_at": "2015-04-23T07:40:03Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Retrieve a zone

GET /:account/zones/:zone

Parameters

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

Example

Get 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

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 1,
    "account_id": 1010,
    "name": "example-alpha.com",
    "reverse": false,
    "secondary": false,
    "last_transferred_at": null,
    "active": true,
    "created_at": "2015-04-23T07:40:03Z",
    "updated_at": "2015-04-23T07:40:03Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Download a zone file

GET /:account/zones/:zone/file

Parameters

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

Example

Get the zone file example.com in the account 1010:

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

Response

Responds with HTTP 200 on success.

{
  "data": {
    "zone": "$ORIGIN example.com.\n$TTL 1h\nexample.com. 3600 IN SOA ns1.dnsimple.com. admin.dnsimple.com. 1453132552 86400 7200 604800 300\nexample.com. 3600 IN NS ns1.dnsimple.com.\nexample.com. 3600 IN NS ns2.dnsimple.com.\nexample.com. 3600 IN NS ns3.dnsimple.com.\nexample.com. 3600 IN NS ns4.dnsimple.com.\n"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Check zone distribution

GET /:account/zones/:zone/distribution

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

This feature can’t be tested in our Sandbox environment.

Parameters

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

Example

Check the zone 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/distribution

Response

Responds with HTTP 200 when the zone is fully distributed.

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

Responds with HTTP 200 when the zone is not distributed.

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

Errors

Responds with HTTP 401 in case of authentication issues.

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

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

Activate DNS services for the zone

This endpoint is currently in Public Preview. During the Preview, period changes may occur at any time.

Consider using our official clients to reduce the likelihood of breaking changes. If you are using or planning to use this endpoint we'd like to hear your feedback.

PUT /:account/zones/:zone/activation

Activates DNS services for the zone.

Under Solo and Teams plans, active zones are charged when renewing your subscription to DNSimple.

Parameters

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

Example

Activate DNS services for example.com in the account 1010:

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

Response

Responds with HTTP 200 when the zone was successfully activated.

{
  "data": {
    "id": 1,
    "account_id": 1010,
    "name": "example.com",
    "reverse": false,
    "secondary": false,
    "last_transferred_at": null,
    "active": true,
    "created_at": "2022-09-28T04:45:24Z",
    "updated_at": "2023-07-06T11:19:48Z"
  }
}

Errors

Responds with HTTP 404 if the resource does not exist.

Deactivate DNS services for the zone

This endpoint is currently in Public Preview. During the Preview, period changes may occur at any time.

Consider using our official clients to reduce the likelihood of breaking changes. If you are using or planning to use this endpoint we'd like to hear your feedback.

DELETE /:account/zones/:zone/activation

Deactivates DNS services for the zone.

Under Solo and Teams plans, active zones are charged when renewing your subscription to DNSimple.

Parameters

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

Example

Activate DNS services for example.com in the account 1010:

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

Response

Responds with HTTP 200 when the zone has been successfully deactivated.

{
  "data": {
    "id": 1,
    "account_id": 1010,
    "name": "example.com",
    "reverse": false,
    "secondary": false,
    "last_transferred_at": null,
    "active": false,
    "created_at": "2022-09-28T04:45:24Z",
    "updated_at": "2023-08-08T04:19:52Z"
  }
}

Errors

Responds with HTTP 404 if the resource does not exist.