Conventions

Conventions the whole API follows

Services are the product

A service is a named thing that runs, each with its own preview URL. Projects are billing groups with budgets and policy; domains and email addresses are org-level assets attached to services and inboxes.

Explicit retry semantics

Operations that declare an Idempotency-Key header use it for transport-safe retries. Retrying with the same key and body replays the stored response instead of re-executing — safe for flaky networks and looping agents alike. The operation says whether the header is optional or required. A replay is marked by replayed: true at the envelope top level and Idempotency-Replayed: true in the response header. Onboarding uses fresh sessions, secret-bound idempotent polls, or unique-email deduplication as documented on each operation. A one-time holder decision instead uses its signed gate as a compare-and-set capability and deliberately does not accept agent authorization.

Responses name the next step

Every successful public mutation arrives in this envelope: { data: { …, receipt, undo, budgetRemainingUsd }, actions, formatVersion, replayed? }. The receipt records the action, costs, and created-resource references; undo is either a concrete reversal or an explicit { command: null, irreversible: true } marker. The top-level actions array is non-empty and ordered, and every entry is typed — tool, url, manual, or an explicit stop for terminal responses. There is no free-form next-step prose. Authority handoffs name the holder, agent, or auditor and spell out required headers and prior steps.

Structured errors, never bare codes

Errors are { blockedBy, message, retryable, actions } with namespaced causes (budget:*, policy:*, plan:*, …). actions is non-empty and typed: it names the exact legitimate path forward — a tool to call, a URL a human must open, a task to poll — rather than describing one in prose. When code is present it equals blockedBy. Human dashboards may additionally project a resolution object; agent paths do not. Envelopes validate against the published JSON Schema.

Humans approve irreversible actions

Domain purchases and budget raises wait for a human decision through a one-tap link or the dashboard by default. A human can grant a key the buy_domain scope to skip the per-purchase gate. There is deliberately no agent-reachable approval endpoint; a leaked gate id resolves nothing.

Long-running work returns a task

Launches, teardowns, and email setup return 202 with a task handle. Poll GET /v1/tasks/{id}; input_required surfaces the approval URL your human needs.

Rate limits on anonymous surfaces

Search, quotes, and signup are rate-limited per caller. A 429 comes with retryable: true — back off for the documented interval and follow its typed actions. When the operation declares an Idempotency-Key, retry the same body with the same key. Read-only search and onboarding instead use the retry or deduplication behavior documented on those operations; do not invent an idempotency header they do not declare.

Export a project with one call

POST /v1/projects/{id}/export returns the full leave package (zone files, site assets, audit ledger). Registrar transfer-out is a separate signed-in action for each domain: name.com is self-service; legacy Cloudflare is operator-assisted. On supported name.com domains, set_registrant_contact records the human as ICANN registrant. The governance model is an open specification, and the current continuity state documents the remaining operator and custody limits.