# Domain Management (https://developer.godaddy.com/en/docs/references/rest/domains/v3/domain-management)

***

title: Domain Management
description: >
Non-commercial async mutations on owned domain instances: contacts,
nameservers, privacy, auto-renew, and transfer-lock. All sub-resources of
/domain-names/. All mutations return a DomainOperation for
polling.
full: true
\_openapi:
method: PUT
toc:

* depth: 2
  title: Replace the nameservers for a domain
  url: '#replace-the-nameservers-for-a-domain'
  structuredData:
  headings:
  * content: Replace the nameservers for a domain
    id: replace-the-nameservers-for-a-domain
    contents:
  * content: >
    Replaces the authoritative nameservers for the domain with the
    provided list. Minimum 2, maximum 13. Returns a DomainOperation;
    propagation to the registry is asynchronous.
    heading: replace-the-nameservers-for-a-domain

***

## 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` | string <uuid> | 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:

- array — Ordered list of authoritative nameserver hostnames for a domain. The first entry is primary; subsequent entries are secondaries. A minimum of two nameservers is required; the maximum is thirteen.
  - items:

### Responses

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

Content-Type: `application/json`

Schema:

- object — The abstract operation envelope for all domain mutations, returned by the universal GET /operations/{operationId} endpoint. Concrete specializations — Registration, Renewal, and Transfer — are returned directly by their respective POST endpoints and carry the same operationId. Developers who do not need the abstract view can poll the concrete resource (GET /registrations/{id}, etc.) and ignore this type entirely.
  - `operationId` (required): allOf(string <uuid> & unknown)
  - `type` (required): allOf(string & unknown)
  - `domain`: string — The domain name this operation applies to.
  - `status` (required): allOf(string & unknown)
  - `result`: allOf(object & unknown)
  - `error`: allOf(object & unknown)
  - `links`: array — HATEOAS link relations for this operation. rel=self — the canonical URL for this abstract operation view. rel=registration, rel=renewal, or rel=transfer — the same resource viewed through its concrete typed collection. rel=domain — the domain-name resource affected by this operation.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.
  - `createdAt`: allOf(string & unknown)
  - `updatedAt`: allOf(string & unknown)

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

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

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

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

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

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

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

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

**422** — Semantically invalid request — valid structure but violates a business rule, such as an ineligible contact, unsupported TLD, or non-renewable domain status.

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

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

Content-Type: `application/json`

Schema:

- object — The error information.
  - `name` (required): string — The human-readable, unique name of the error.
  - `correlationId` (required): string — Internal identifier used for correlation purposes.
  - `message` (required): string — The message that describes the error.
  - `informationLink`: string — The URI for detailed information related to this error for the developer.
  - `details`: array — An array of additional details about the error. Required for client-side `4XX` errors.
      - items:
          - `field`: string — The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors.
          - `value`: string — The value of the field that caused the error.
          - `location`: string — The location of the field that caused the error. Value is `body`, `path`, or `query`.
          - `issue` (required): string — The unique fine-grained application-level error code.
          - `description`: string — The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value.
  - `links`: array — An array of error-related HATEOAS links.
      - items:
          - `href` (required): string <uri> — The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          - `rel` (required): string — The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          - `title`: string — The link title.
          - `targetMediaType`: string — The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.
          - `targetSchema`: unknown — The schema that describes the link target.
          - `method`: string — The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.
          - `submissionMediaType`: string — The media type with which to submit data with the request.
          - `submissionSchema`: unknown — The schema that describes the request data.

**Security:** requires `bearerAuth`.