# Domains REST reference (https://developer.godaddy.com/en/docs/references/rest/domains)



<Callout type="info" title="Machine-readable specs">
  The complete OpenAPI specs for this namespace are available as JSON — useful for code generation, SDK tooling, and LLM context: [domains-v3.json](https://developer.godaddy.com/openapi/domains-v3.json) (discovery + registration), [domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) (account-scoped), and [domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json) (async operations).
</Callout>

The Domains REST API exposes domain availability search, registration, DNS and contact management, registry lock, WHOIS privacy, forwarding, and inbound and outbound transfers. Operations span three version namespaces: `v3` (quote-execute registration model), `v1` (account-scoped), and `v2` (async operation tracking).

For a task-shaped guide written for DIY API users, see [Use the API → Domains](https://developer.godaddy.com/docs/api-users/manage-domains).

## The core objects

The Domains namespace is built around a small set of resources. Each operation in the reference reads or writes one of these objects.

| Object                                      | Description                                                                                                                                                                                                       |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DomainDetail` (v1) / `DomainDetailV2` (v2) | A registered domain and its registry metadata: name, status, expiration, contacts, nameservers, lock state, and privacy state.                                                                                    |
| `DNSRecord`                                 | A single DNS record (`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `SOA`, or `CAA`) on a domain that uses GoDaddy's authoritative nameservers.                                                                  |
| `Contact`                                   | A WHOIS contact record covering name, organization, address, email, and phone. The same shape is used for the registrant, admin, billing, and tech roles on a domain.                                             |
| `Action`                                    | An asynchronous-operation tracker returned with `202 Accepted` when the API queues a long-running write. Callers poll the action endpoint until the action's `status` reaches a terminal state.                   |
| `DomainAvailableResponse`                   | The result of an availability check, including the available flag, current price in `currency-micro-unit` format, the registration period in years, and whether the answer is from a live registry call or cache. |
| `DomainForwarding`                          | An HTTP forwarding rule on a domain, configurable as masked or unmasked and as a permanent (`301`) or temporary (`302`) redirect.                                                                                 |
| `DomainTransferIn`                          | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts.                                                                                                             |
| `Error` / `ErrorLimit`                      | The standard error envelope returned on `4xx` and `5xx` responses across the namespace. `ErrorLimit` extends `Error` with `retryAfterSec` for `429` rate-limited responses.                                       |

## Version namespaces

<Cards>
  <Card title="v3 — quote-execute model" description="Discovery (check-availability, suggestions) and registration via a quote-execute flow. All writes are async with a poll URL. v3 does not yet cover DNS, renewals, transfers, contacts, forwarding, or privacy." href="/docs/references/rest/domains/v3" />

  <Card title="v1 — account-scoped" description="Operations under /v1/domains/... act on the domains owned by the authenticated account. Use for DNS, contacts, privacy, renewals, transfers, and anything not yet in v3." href="/docs/references/rest/domains/v1" />

  <Card title="v2 — async operations" description="v1 capabilities plus async operation tracking — action queues, status polling, notifications, and forwarding. Use when you need to track long-running writes like transfers and redemptions." href="/docs/references/rest/domains/v2" />
</Cards>

## Conventions used across the namespace

| Concern                                                        | Where it's documented                      |
| -------------------------------------------------------------- | ------------------------------------------ |
| Authentication (PAT for v3; PAT or legacy `sso-key` for v1/v2) | [Authentication](https://developer.godaddy.com/docs/api-users/auth)     |
| Error envelope and retry semantics                             | [Errors](https://developer.godaddy.com/docs/api-users/errors)           |
| Rate limits (60 requests/minute per credential)                | [Rate limits](https://developer.godaddy.com/docs/api-users/rate-limits) |
| Cursor-based pagination on v1 list endpoints                   | [Pagination](https://developer.godaddy.com/docs/api-users/pagination)   |

## Related references

<Cards>
  <Card title="Shoppers REST reference" description="Shopper account and subaccount management used by the X-Shopper-Id header on v1 Domains operations." href="/docs/references/rest/shoppers/shoppers" />
</Cards>