> ## Documentation Index
> Fetch the complete documentation index at: https://docs.namegrid.org/llms.txt
> Use this file to discover all available pages before exploring further.

# PATCH /domains/{domain}/nameservers — Set Nameservers

> Replace a domain's nameservers with a new set of 2–13 valid hostnames. Changes apply immediately, or are queued if provisioning is still in progress.

Use this endpoint to replace the nameservers for a domain in your workspace. The operation performs a full replacement — the list you provide becomes the complete set of nameservers for the domain, and any previously configured nameservers are removed. This is how you point a domain at your own DNS infrastructure or a third-party DNS provider.

## Request

**Method:** `PATCH`\
**Path:** `/v1/domains/{domain}/nameservers`

| Header         | Required | Value              |
| -------------- | -------- | ------------------ |
| `x-api-key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Path Parameters

<ParamField path="domain" type="string" required>
  The domain name whose nameservers you want to update (e.g. `example.com`).
</ParamField>

### Body Parameters

<ParamField body="nameservers" type="string[]" required>
  An array of 2 to 13 fully-qualified nameserver hostnames (e.g. `["ns1.example.com", "ns2.example.com"]`). Each entry must be a valid hostname string. The order of the array is preserved.
</ParamField>

<Note>
  If the domain hasn't been fully provisioned yet (for example, it was registered very recently and is still propagating), the nameserver changes are saved immediately and will be applied automatically once provisioning completes. The `pendingFulfillment: true` flag in the response indicates this state.
</Note>

### Request Example

```bash theme={null}
curl -X PATCH https://api.namegrid.org/v1/domains/example.com/nameservers \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "nameservers": ["ns1.example.com", "ns2.example.com"] }'
```

## Response — 200 OK

<ResponseField name="nameservers" type="string[]">
  The updated list of nameserver hostnames now assigned to the domain, in the order they were provided.
</ResponseField>

<ResponseField name="pendingFulfillment" type="boolean">
  `true` if the domain is still being provisioned and the nameserver change will be applied automatically once the registration completes. `false` if the change was applied immediately.
</ResponseField>

```json theme={null}
{
  "nameservers": ["ns1.example.com", "ns2.example.com"],
  "pendingFulfillment": false
}
```

## Errors

| Status | Reason                                                                                  |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Fewer than 2 or more than 13 nameservers provided, or one or more hostnames are invalid |
| `404`  | The domain does not exist or is not owned by your workspace                             |