# Replace the nameservers for a domain (https://developer.godaddy.com/en/docs/references/rest/domains/v3/update-nameservers)

---
title: Replace the nameservers for a domain
description: Replaces the authoritative nameservers for the domain with the provided list.
full: true
---

Full description

> Replaces the authoritative nameservers for the domain with the provided list. Minimum 2, maximum 13. Returns a DomainOperation; propagation to the registry is asynchronous.

## PUT /domain-names/{domain-name}/nameservers

Replace the nameservers for a domain

Replaces the authoritative nameservers for the domain with the provided list. Minimum 2, maximum 13. Returns a DomainOperation; propagation to the registry is asynchronous.


### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `domain-name` | string | yes | The domain name in punycode A-label form (e.g., example.com). For IDNs, use the punycode representation. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Request-Id` | unknown | no | Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header. |
| `Idempotency-Key` | string | yes | Client-generated unique key (UUID recommended). Retrying a mutating request with the same Idempotency-Key returns the original response without creating a duplicate side effect. Required on all execute endpoints. |

### Request body (required)

Content-Type: `application/json`

```json
[
  "ns1.example.com",
  "ns2.example.com"
]
```

Schema:

- schema reference: `#/components/schemas/NameServers`

### Responses

**202** — Nameserver update accepted; poll the operation for completion.

Content-Type: `application/json`

Schema:

- schema reference: `#/components/schemas/DomainOperation`

**400** — Malformed request syntax, missing required field, or invalid field type.

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**401** — Authentication credentials are missing or invalid.

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**403** — Authenticated identity is not authorized to perform this operation.

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**404** — The requested resource was not found.

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, non-renewable domain status, or quote_mismatch (e.g. iscCode or acknowledgedFees that do not match the locked quote).

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**429** — Too many requests — rate limit exceeded.

Content-Type: `application/json`

Schema:

- schema reference: `#/x-ext/21ae8c5`

**Security:** requires `bearerAuth`.