Name servers and delegation API

Retrieve and manage delegation for a domain in DNSimple.

Note

The canonical DNSimple name server hostnames are ns1.dnsimple-edge.com, ns2.dnsimple-edge.net, ns3.dnsimple-edge.io, and ns4.dnsimple-edge.org. The legacy ns1.dnsimple.com through ns4.dnsimple.com hostnames still resolve and answer from the same edge infrastructure, so a delegation that references them keeps working and this API accepts either form. The legacy IP addresses behind ns1.dnsimple.com and ns3.dnsimple.com were decommissioned on 6 July 2026, so an integration that writes glue records or A/AAAA records for name servers by IP must use the current addresses. See Discontinuation of Legacy NS1 and NS3 IP Addresses for the addresses and the migration timeline.

List domain name servers

GET /:account/registrar/domains/:domain/delegation

List name servers for the domain in the account.

Parameters

Name Type Description
:account integer The account id
:domain string, integer The domain name or id

Example

List name servers for the domain example.com in the account 1010:

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

Response

Responds with HTTP 200.

{
  "data": [
    "ns1.dnsimple-edge.com",
    "ns2.dnsimple-edge.net",
    "ns3.dnsimple-edge.io",
    "ns4.dnsimple-edge.org"
  ]
}

Errors

Responds with HTTP 401 in case of case of authentication issues.

Change domain name servers

PUT /:account/registrar/domains/:domain/delegation

Parameters

Name Type Description
:account integer The account id
:domain string, integer The domain name or id

Example

Update name servers for the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PUT \
      -d '["ns1.example.com","ns2.example.com"]' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/delegation

Input

Name Type Description
  array Required A list of name server names as strings.
Example
[
  "ns1.example.com",
  "ns2.example.com"
]

Response

Responds with HTTP 200 on success.

{
  "data": [
    "ns1.dnsimple-edge.com",
    "ns2.dnsimple-edge.net",
    "ns3.dnsimple-edge.io",
    "ns4.dnsimple-edge.org"
  ]
}

Errors

Responds with HTTP 400 if the name servers cannot be changed.

Responds with HTTP 401 in case of case of authentication issues.

Delegate to vanity name servers

Note

This method required the vanity name servers feature, that is only available for certain plans. If the feature is not enabled, you will receive an HTTP 412 response code.

PUT /:account/registrar/domains/:domain/delegation/vanity

Parameters

Name Type Description
:account integer The account id
:domain string, integer The domain name or id

Input

Name Type Description
  array Required A list of name server names as strings.

Example

Update name servers for the domain example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PUT \
      -d '["ns1.example.com","ns2.example.com"]' \
      https://api.dnsimple.com/v2/1010/registrar/domains/example.com/delegation/vanity

Response

Responds with HTTP 200 on success, renders the list of name server names.

{
  "data": [
    {
      "id": 1,
      "name": "ns1.example.com",
      "ipv4": "127.0.0.1",
      "ipv6": "::1",
      "created_at": "2016-07-11T09:40:19Z",
      "updated_at": "2016-07-11T09:40:19Z"
    },
    {
      "id": 2,
      "name": "ns2.example.com",
      "ipv4": "127.0.0.1",
      "ipv6": "::1",
      "created_at": "2016-07-11T09:40:19Z",
      "updated_at": "2016-07-11T09:40:19Z"
    }
  ]
}

Errors

Responds with HTTP 400 if the domain cannot be delegated to the vanity name servers.

Responds with HTTP 401 in case of case of authentication issues.

Responds with HTTP 412 if the account doesn’t have access to the vanity name servers feature.

Dedelegate from vanity name servers

Note

This method required the vanity name servers feature, that is only available for certain plans. If the feature is not enabled, you will receive an HTTP 412 response code.

DELETE /:account/registrar/domains/:domain/delegation/vanity

Parameters

Name Type Description
:account integer The account id
:domain string, integer The domain name or id

Example

Update name servers for the domain example.com in the account 1010:

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

Response

Responds with HTTP 204 on success.

Errors

Responds with HTTP 400 if the domain cannot be dedelegated from the vanity name servers.

Responds with HTTP 401 in case of case of authentication issues.

Responds with HTTP 412 if the account doesn’t have access to the vanity name servers feature.