Domains v2
View as MarkdownDomains v2 — v1 capabilities plus async operation tracking. Action queues, status polling, notifications, forwarding, and registration under /v2/customers/{customerId}/domains.
Overview
The v2 namespace extends the Domains API with async operation tracking — action queues, status polling, and lifecycle notifications. Operation paths follow /v2/customers/{customerId}/domains/....
Use v2 when you need to track long-running writes (transfers, redemptions) that return 202 Accepted instead of completing synchronously. For a task-shaped guide layered on top of these endpoints, see Use the API → Domains.
Machine-readable spec
The complete OpenAPI spec for the v2 namespace is available at /openapi/domains-v2.json — useful for code generation, SDK tooling, and LLM context.
Operation groups
The v2 namespace is organized into seven operation groups, each rendered on its own reference page below.
Registration
Operations for registering a domain on behalf of a customer, including contact validation, schema retrieval, and registry-usage reporting.
Management
Operations for retrieving a domain, updating its nameservers, renewing it, and redeeming it from grace period.
Transfer
Operations for inbound and outbound transfers, including accept, reject, restart, and change-of-registrant flows.
Forwarding
Operations for creating, updating, listing, and deleting HTTP forwarding rules on a domain, including privacy-side forwarding.
Actions
Operations for tracking the status of asynchronous writes returned with 202 Accepted, including listing, fetching by type, and cancellation.
Notifications
Operations for subscribing to, retrieving, and acknowledging domain lifecycle notifications, plus their payload schemas.
Authentication and scopes
Every v2 operation requires an Authorization header carrying a Personal Access Token (Bearer) or a legacy sso-key credential. The principal must additionally be authorized for the customer named in the URL. PATs use the granular Domains & DNS scopes listed in Authentication, such as domains.domain:read, domains.domain:update, and domains.transfer:execute.
v2-only capabilities
Some operations have no v1 equivalent and must be reached through v2:
- Domain forwarding (HTTP redirects on a domain).
- Notification subscriptions (lifecycle events delivered to a callback or pulled on demand).
- Customer-scoped change-of-registrant (managed across customer boundaries).
Conventions
| Concern | Where it's documented |
|---|---|
| Error envelope and retry semantics | Errors |
| Rate limits (60 requests/minute per credential) | Rate limits |
Asynchronous-write polling via the Action resource | Actions reference |
Agent & Automation Notes
domains.domain:read, domains.domain:create, domains.domain:update, domains.contact:update, domains.nameserver:update, domains.transfer:execute, domains.transfer:update, domains.forward:updateRelated
Last updated on
How is this guide?
Operations GET
Abstract operation polling. Poll GET /operations/{operationId} for any domain mutation until it reaches COMPLETED or FAILED. Operation IDs are unique across Registration, Renewal, and Transfer — clients that prefer typed polling can use the concrete resource endpoints instead.
Register Domains
Register new domains, retrieve registration schemas by TLD, and validate registration requests.