Name servers

This section is about delegation — which name servers answer for the domain — and DNSSEC. For editing the actual records inside a zone (A, MX, TXT and so on), see DNS records.

These all live under the domain path

DNS, DNSSEC and zone management are not separate services — every path in this section and in DNS records sits under /api/v1/domains/, and in the interactive API explorer the DNS and DNSSEC operations are listed together with the rest of the Domain group:

/api/v1/domains                      domain operations      (Domains)
/api/v1/domains/dns                  name servers           (this section)
/api/v1/domains/dns/host             host / glue records    (this section)
/api/v1/domains/dns/dnssec           DS records             (this section)
/api/v1/domains/zones                DNS records            (DNS records)

They are split into separate chapters here because they are separate jobs, not because they are separate parts of the API. Your API key and the domain’s ownership rules apply identically across all of them.

Which section do you need?

You want to…	Use
Point the domain at someone else’s name servers	PUT /domains/dns/name-server — this section
Point the domain at our name servers	PUT /domains/dns/name-server, or POST /domains/zones/apply
Run your own name servers under the domain (ns1.apiname.com)	POST /domains/dns/host — this section
Add an A, MX, TXT, CNAME record	DNS records
Enable DNSSEC	POST /domains/dns/dnssec — this section
:::

One rule applies to every call in this section

No DNS change is accepted while the domain is waiting for registry documents. You get Dna.DomainService:Domain:10070. Resolve the document flow first. The host endpoints additionally require the domain to be active.

Changing name servers

PUT /api/v1/domains/dns/name-server

Replaces the domain’s name servers. This is a wholesale replacement, not an add or remove — send the complete list you want the domain to end up with.

Request

Field	Required	Notes
domainName	required
nameServers	required	The complete new set. Count must satisfy the TLD’s minimum and maximum — usually 2 to 13. No duplicates.
dnssecMode	conditional	Required when DNSSEC is active on the domain. See below. Defaults to 0, which blocks the change.

Move to a third-party DNS provider

{
  "domainName": "apiname.com",
  "nameServers": ["ns1.otherhost.com", "ns2.otherhost.com"]
}

Move to our DNS, so you can use the zones API

{
  "domainName": "apiname.com",
  "nameServers": ["tr.apiname.com", "eu.apiname.com"]
}

Response — 204, no body

Set up the new DNS before you switch

The moment resolvers pick up the new delegation, the old name servers stop being authoritative. If the new ones do not yet have your records, the website and e-mail go down.

Create the zone and all its records at the new provider first, verify them, then change the delegation. Expect up to 48 hours for the change to reach every resolver worldwide on a first-time switch.

dnssecMode — only relevant when DNSSEC is active

Changing name servers on a DNSSEC-signed domain breaks it unless the new provider publishes keys matching the published DS records. We refuse to do that silently, so you have to state your intent.

Value	Name	Behaviour
0	Block	Default. The change is refused with Dna.DomainService:Dnssec:10010. This is deliberate — it stops you breaking the domain by accident.
1	KeepDnssec	You confirm the new provider already publishes keys matching the existing DS records. The DS records stay and the name servers change. If you are wrong, the domain becomes unresolvable for validating resolvers.
2	DisableDnssec	The safe option. All DS records are removed from the registry first, then the name servers change. If removal fails, the name servers are left alone.

Recommended DNSSEC-safe move

Unless you have deliberately arranged key continuity with the new provider, use "dnssecMode": 2. Re-enable DNSSEC afterwards with the new provider’s DS records. Domains lose DNSSEC protection briefly but never become unresolvable.

Errors

Code	Meaning and fix
Dna.DomainService:Domain:10007	Domain not found or not yours.
Dna.DomainService:Domain:10044	Invalid domain name.
Dna.DomainService:Domain:10070	The domain is waiting for registry documents.
Dna.DomainService:Dns:10005	nameServers is empty.
Dna.DomainService:Dns:10022	Too few or too many for this TLD. Check the catalogue.
Dna.DomainService:Dns:10013	Duplicate entry in the list.
Dna.DomainService:Dns:10025	The change would drop below the TLD’s minimum.
Dna.DomainService:Dns:10016	A name server under this domain needs a glue IP. Create the host record first — see below.
Dna.DomainService:Dns:10026	IPv6 glue not supported by this TLD.
Dna.DomainService:Dnssec:10010	DNSSEC is active and dnssecMode is 0. Pick 1 or 2.
Dna.DomainService:Dnssec:10011	You chose DisableDnssec but the DS records could not be removed. Nothing was changed. details carries the registry’s message.
Dna.DomainService:Dnssec:10012	DS removal is queued for registry approval. Retry the name-server change once it completes.
Dna.DomainService:DomainSale:10007	The domain is listed for sale and uses parking records.
Dna.DomainService:Epp:10001	The registry rejected the change.