# Name servers

> Change which name servers answer for a domain, and how an active DNSSEC setup affects the change.

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](https://www.domainnameapi.com/docs/dns-records/).

:::note[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:

```text
/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.
:::

:::note[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](https://www.domainnameapi.com/docs/dns-records/) |
| Enable DNSSEC | `POST /domains/dns/dnssec` — this section |
:::

:::caution[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](https://www.domainnameapi.com/docs/domains/documents/) 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**

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

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

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

**Response — 204, no body**

:::danger[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. |

:::tip[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. |