Secondary DNS API

This article describes a feature in Public Beta.

During the beta period, changes to the individual endpoints 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.

Table of Contents

Primary Server attributes

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

List primary servers

GET /:account/secondary_dns/primaries

List primary servers for in the account.

Parameters

Name Type Description
:account integer The account id

Sorting

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

Name Description
id Sort primary servers by ID
name Sort primary serves by name (alphabetical order)

The default sorting policy is by ascending id.

Example

List all primary servers in the account 1010:

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

Response

Responds with HTTP 200 on success.

{
  "data": [
    {
      "id": 1,
      "account_id": 531,
      "name": "Primary",
      "ip": "1.1.1.1",
      "port": 4567,
      "linked_secondary_zones": [

      ],
      "created_at": "2021-03-05T18:02:23Z",
      "updated_at": "2021-03-05T18:02:23Z"
    },
    {
      "id": 2,
      "account_id": 531,
      "name": "Primary Production",
      "ip": "1.1.1.1",
      "port": 4567,
      "linked_secondary_zones": [
        "secondaryzone.com"
      ],
      "created_at": "2021-03-16T20:33:34Z",
      "updated_at": "2021-03-16T20:33:34Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Create a primary server

POST /:account/secondary_dns/primaries

Parameters

Name Type Description
:account integer The account id

Example

Create a primary server 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/secondary_dns/primaries

Input

Name Type Description
name string Required. The name of the primary server.
ip string Required. The IP of the primary server.
port integer The port of the primary server.
Example
{
  "name": "Primary Production",
  "ip": "1.2.3.4",
  "port": 4567
}

Response

Responds with HTTP 201 on success, renders the primary server.

{
  "data": {
    "id": 4,
    "account_id": 531,
    "name": "PrimaryProduction",
    "ip": "1.2.3.4",
    "port": 53,
    "linked_secondary_zones": [

    ],
    "created_at": "2021-03-17T23:08:42Z",
    "updated_at": "2021-03-17T23:08:42Z"
  }
}

Errors

Responds with HTTP 400 if the primary server cannot be created.

Responds with HTTP 401 in case of authentication issues.

Retrieve a Primary Server

GET /:account/secondary_dns/primaries/:primary_server

Parameters

Name Type Description
:account integer The account id
:primary_server integer The primary server id

Example

Get the primary server with the ID 1 in the account 1010:

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

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 4,
    "account_id": 531,
    "name": "PrimaryProduction",
    "ip": "1.2.3.4",
    "port": 53,
    "linked_secondary_zones": [

    ],
    "created_at": "2021-03-17T23:08:42Z",
    "updated_at": "2021-03-17T23:08:42Z"
  }
}

Errors

Responds with HTTP 401 in case of authentication issues.

Delete primary server

DELETE /:account/secondary_dns/primaries/:primary_server

Delete the primary server from the account.

Parameters

Name Type Description
:account integer The account id
:primary_server integer The primary server id

Example

Delete the primary server with ID 1 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/secondary_dns/primaries/1

Response

Responds with HTTP 204 on success.

Errors

Responds with HTTP 401 in case of authentication issues.

Link a primary server to a secondary zone

PUT /:account/secondary_dns/primaries/:primary_server/link

Parameters

Name Type Description
:account integer The account id
:primary_server integer The primary server id

Example

Link the primary server 1 to a secondary zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PUT \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/secondary_dns/primaries/1/link

Input

Name Type Description
zone string Required. The zone name to link with. Should be a secondary zone.
Example
{
  "zone": "example.com"
}

Response

Responds with HTTP 200 on success. The linked zone will be present in the linked_secondary_zones attribute.

{
  "data": {
    "id": 4,
    "account_id": 531,
    "name": "PrimaryProduction",
    "ip": "1.2.3.4",
    "port": 53,
    "linked_secondary_zones": [
      "secondaryzone.com"
    ],
    "created_at": "2021-03-17T23:08:42Z",
    "updated_at": "2021-03-17T23:08:42Z"
  }
}

Errors

Responds with HTTP 400 if the primary server cannot be linked to the secondary zone.

Responds with HTTP 401 in case of authentication issues.

Unlink a primary server from a secondary zone

PUT /:account/secondary_dns/primaries/:primary_server/unlink

Parameters

Name Type Description
:account integer The account id
:primary_server integer The primary server id

Example

Unlink the primary server 1 from a secondary zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PUT \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/secondary_dns/primaries/1/unlink

Input

Name Type Description
zone string Required. The zone name to unlink from. Should be a secondary zone.
Example
{
  "zone": "example.com"
}

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 4,
    "account_id": 531,
    "name": "PrimaryProduction",
    "ip": "1.2.3.4",
    "port": 53,
    "linked_secondary_zones": [

    ],
    "created_at": "2021-03-17T23:08:42Z",
    "updated_at": "2021-03-17T23:08:42Z"
  }
}

Errors

Responds with HTTP 400 if the primary server cannot be unlinked from the secondary zone.

Responds with HTTP 401 in case of authentication issues.

Create a secondary zone

POST /:account/secondary_dns/zones

When creating a secondary zone using Solo or Teams subscription, the DNS services for the zone will be automatically enabled. This will be charged on your following subscription renewal invoices.

Parameters

Name Type Description
:account integer The account id

Example

Create a secondary zone 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/secondary_dns/zones

Input

Name Type Description
name string Required. The name of the secondary zone.
Example
{
  "name": "secondaryexample.com"
}

Response

Responds with HTTP 201 on success. The attribute secondary will be true.

{
  "data": {
    "id": 734,
    "account_id": 531,
    "name": "secondaryexample.com",
    "reverse": false,
    "secondary": true,
    "last_transferred_at": null,
    "created_at": "2021-03-17T23:44:27Z",
    "updated_at": "2021-03-17T23:44:27Z"
  }
}

Errors

Responds with HTTP 400 if the secondary zone cannot be created.

Responds with HTTP 401 in case of authentication issues.

Delete secondary zone

Please refer to the Domain deletion endpoint