# Browse the Domains API (https://developer.godaddy.com/en/docs/api-users/domains/manage) --- title: Browse the Domains API description: 'The Domain object, related resources, and task-grouped operations.' keywords: >- DomainDetail schema, DomainDetailV2, renewAuto, locked field, nameServers, contactRegistrant, ACTIVE EXPIRED PENDING_TRANSFER, domain status values related: apis: - title: Domains v3 reference href: /docs/references/rest/domains/v3 - title: Domains v1 reference href: /docs/references/rest/domains/v1 - title: Domains v2 reference href: /docs/references/rest/domains/v2 guides: - title: Quickstart href: /docs/api-users/quickstart - title: Authenticate href: /docs/api-users/auth - title: Search domain availability href: /docs/api-users/domains/search - title: Register a domain href: /docs/api-users/domains/register pageId: 53ca20f3-72b2-42e8-994c-dd8c4325d2a2 --- ## Overview The Domains API supports availability search, registration, DNS and contact management, registry lock, forwarding, and inbound transfers. Operations span three version namespaces. v3 is the preferred API for domain registration, v1 and v2 provide everything else (DNS, renewals, transfers, and customer actions). ## Version namespaces The following table lists the version namespaces and what they contain. | Version | Base path | What's here | | ------- | ---------------------------------------- | ----------------------------------------------------------------------------------- | | v3 | `/v3/domains/...` | Availability checks and registration (the preferred namespace for new integrations) | | v2 | `/v2/customers/{customerId}/domains/...` | v1 capabilities with async processing and operations tracking | | v1 | `/v1/domains/...` | List, DNS, contacts, lock, and renewals | ## The Domain object A domain registered or managed through this API is the central resource of the Domains namespace. It carries registry metadata, expiration and renewal state, the four WHOIS contact roles, registry lock and privacy flags, and the authoritative nameservers returned at the TLD. Almost every operation in this namespace either returns a `DomainDetail` or modifies a field on one. The schema is named `DomainDetail` in v1 and `DomainDetailV2` in v2. The two are largely overlapping; v2 extends v1 with async operation tracking — the `DomainDetailV2` schema adds status values and action references used by long-running writes like transfers and redemptions. For single-domain detail, prefer v2: it returns more consistent status values and exposes async operation tracking if you need it. The following table lists the key fields on a `DomainDetail` object. | Field | Description | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `domain` | Fully-qualified domain name (for example `example.com`). | | `status` | Current registry or registrar state, like `ACTIVE`, `PENDING_TRANSFER`, or `EXPIRED`. | | `expires` | Expiration timestamp in ISO-8601 format. | | `renewAuto` | Whether auto-renew is enabled on the domain. | | `locked` | Whether the registry transfer-lock is engaged. | | `privacy` | Whether WHOIS privacy is purchased and active. | | `nameServers` | Authoritative nameservers the registry returns for the domain. | | `contactRegistrant` / `contactAdmin` / `contactBilling` / `contactTech` | The four WHOIS contact roles, each a `Contact` object. | The full schema is in the OpenAPI specs, available as machine-readable JSON at [/openapi/domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) and [/openapi/domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json). Go to the [Domains REST reference](https://developer.godaddy.com/docs/references/rest/domains) for the complete API reference. ### Related objects Every operation in the Domains namespace returns or accepts one of the following objects in addition to `DomainDetail`. Each links to the rendered reference where its full schema and the operations it appears on are documented. | Object | Description | Reference | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `DNSRecord` | A single DNS record on a domain managed by GoDaddy's authoritative nameservers, supporting `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `SOA`, and `CAA` types. | [v1 DNS operations](https://developer.godaddy.com/docs/references/rest/domains/v1/record-add) | | `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. | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) | | `Action` | An asynchronous-operation tracker returned with `202 Accepted` when the API queues a long-running write (transfers, redemption). Callers poll the action endpoint until the action's `status` reaches a terminal state. | [v2 action operations](https://developer.godaddy.com/docs/references/rest/domains/v2/domain-actions) | | `DomainAvailableResponse` | The result of a single-domain availability check, including the available flag, current price in `currency-micro-unit` format, the registration period in years, and whether the answer came from a live registry call or cache. | [v1 availability operations](https://developer.godaddy.com/docs/references/rest/domains/v1/available) | | `DomainForwarding` | An HTTP forwarding rule that redirects requests for a domain to a target URL, configurable as masked or unmasked and as a permanent (`301`) or temporary (`302`) redirect. | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) | | `DomainTransferIn` | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts. | [v2 transfer operations](https://developer.godaddy.com/docs/references/rest/domains/v2/transfer-domains) | | `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. | [Errors](https://developer.godaddy.com/docs/api-users/errors) | Most Domains API writes complete synchronously and return `204 No Content`. A few long-running operations — transfers, redemption — return `202 Accepted` with an `Action` body instead. Poll `GET /v2/customers/{customerId}/domains/actions/{actionId}` until `status` reaches a terminal state (`COMPLETED`, `FAILED`, or `CANCELLED`). ## Tasks ### Manage existing domains The following table lists the tasks for managing a domain you own: | Page | What it covers | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | | [Registered domains](https://developer.godaddy.com/docs/api-users/domains/manage/list) | Walk a paginated list of the domains owned by the authenticated account, or fetch full detail for a single domain. | | [DNS records and nameservers](https://developer.godaddy.com/docs/api-users/domains/manage/dns) | Read, replace, add, and delete DNS records on a domain, or change which authoritative nameservers the registry returns. | | [Update contacts](https://developer.godaddy.com/docs/api-users/domains/manage/update-contacts) | Change the registrant, admin, billing, or tech contact on a domain you own. | | [Auto-renew and renewals](https://developer.godaddy.com/docs/api-users/domains/manage/renewals) | Toggle auto-renew, manually renew before expiration, or redeem a domain from the grace period. | | [Registry lock](https://developer.godaddy.com/docs/api-users/domains/manage/lock) | Read or toggle the registry transfer-lock state on a domain. | | [Domain forwarding](https://developer.godaddy.com/docs/api-users/domains/manage/forwarding) | Configure HTTP redirect rules on a domain through the v2 forwarding API. | ### Acquire new domains The following table lists the tasks for getting a new domain: | Page | What it covers | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | [Search availability](https://developer.godaddy.com/docs/api-users/domains/search) | Check whether a single name or a list of names is available to register, with current pricing returned in microunits. | | [Purchase a domain](https://developer.godaddy.com/docs/api-users/domains/register) | Buy a name you have confirmed available, including contact data, privacy choice, and TLD-specific agreements. | * [Generate a Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth/how-to). * [Fund your account](https://www.godaddy.com/help/add-a-payment-method-to-my-godaddy-account-20037) for write operations. * [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli/set-up). * [Make your first call](https://developer.godaddy.com/docs/api-users/quickstart).