Browse the Domains API
View as MarkdownThe Domain object, related resources, and task-grouped operations.
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 and /openapi/domains-v2.json. Go to the Domains REST reference 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 |
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 |
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 |
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 |
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 |
DomainTransferIn | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts. | v2 transfer operations |
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 |
Async operations and the Action object
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
Registered domains
Walk a paginated list of the domains owned by the authenticated account, or fetch full detail for a single domain.
DNS records and nameservers
Read, replace, add, and delete DNS records on a domain, or change which authoritative nameservers the registry returns.
Update contacts
Change the registrant, admin, billing, or tech contact on a domain you own.
Auto-renew and renewals
Toggle auto-renew, manually renew before expiration, or redeem a domain from the grace period.
Registry lock
Read or toggle the registry transfer-lock state on a domain.
Domain forwarding
Configure HTTP redirect rules on a domain through the v2 forwarding API.
Acquire new domains
Search availability
Check whether a single name or a list of names is available to register, with current pricing returned in microunits.
Purchase a domain
Buy a name you have confirmed available, including contact data, privacy choice, and TLD-specific agreements.
Transfer a domain in
Move a domain from another registrar to GoDaddy using its authcode, with registry lock and verification handled inline.
Tips
- Generate a Personal Access Token (PAT).
- Fund your account for write operations.
- Set up the CLI.
- Make your first call.
Related
Last updated on
How is this guide?