HeadlessDomains Partners

Registrar developer docs

HTTP Registrar API

A protected registry command surface for registrar integrations before EPP.

Machine-readable spec

The OpenAPI document describes the registrar lifecycle endpoints, scopes, request bodies, and common error responses.

Open OpenAPI JSON Registrar handoff packet Open OT&E checklist OT&E evidence template EPP gateway contract EPP conformance checklist

Endpoint base

/api/v1/registrar/v1

Use a Bearer token from a Partner API key with the registrar API profile or equivalent lifecycle scopes. Registrar API keys must be bound to an approved registrar channel, and that channel must have an approved namespace listing for the requested TLD before command endpoints accept it.

Start every OT&E run with GET /status. It verifies the API key, approved registrar channel, namespace listings, production approval status, rate-limit state, sandbox flags, OT&E test sequence, audit provenance, docs links, and command capability matrix for the exact credential being tested. Each command row includes scope status, missing scopes, sandbox availability, production availability, and a disabled reason when a command is blocked.

Archive audit_provenance.registrar_channel_id from GET /status. New registrar-origin command audits store that exact registrar_channel_id, and GET /poll is filtered to the authenticated channel.

The status response also includes the internal registry service contract and the planned EPP gateway contract, including registry-service EPP command mapping, lifecycle states, audit/idempotency behavior, protected legacy policy, DNS adapter capabilities, and a machine-readable EPP conformance checklist.

Sandbox Mode

Mutating commands accept sandbox: true in the JSON body or X-Registrar-Sandbox: 1. Sandbox requests return 202, write a command audit row with status sandbox, and do not change inventory, balances, nameservers, lifecycle state, or backend records. Retrying the same sandbox command with the same idempotency key and request body returns the recorded response with idempotent: true.

POST /sandbox/reset creates predictable OT&E fixture domains for renewal, nameserver, metadata update, delete/cancel, and claim-required tests. It only overwrites records marked ote_sandbox.

Production Approval

Registrar channels start as OT&E unless an operator marks the channel production_approved. Non-sandbox mutating commands return 403 registrar_channel_not_production_approved until production approval is recorded. Availability checks, reads, status, audit polling, sandbox reset, and sandbox mutations remain available for OT&E.

Idempotency

Production lifecycle commands replay a successful result when the same command, domain, request body, and idempotency_key are submitted again. Reusing a key for a different domain or different request returns 409 duplicate_idempotency_key_conflict.

Rate Limits

Registrar command endpoints are rate-limited per approved registrar channel, API key, endpoint, and minute. The default limit is 120 requests per minute. Excess requests return 429 registrar_rate_limit_exceeded with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error Codes

The OpenAPI document includes x-registrar-error-catalog for machine-readable registrar integration handling. The catalog is shared with the internal registry service contract and includes http_status, epp_result_code, epp_result, and retryable fields so a future EPP gateway can map the same errors without a second translation table.

403 registrar_channel_requiredThe API key is not bound to an approved registrar channel.
403 registrar_namespace_not_approvedThe registrar channel is not approved for the requested namespace.
403 registrar_channel_not_production_approvedThe registrar can run OT&E/sandbox, but production mutation has not been approved.
409 duplicate_idempotency_key_conflictThe idempotency key was reused for a different command, domain, or request body.
429 registrar_rate_limit_exceededThe registrar should honor Retry-After and X-RateLimit headers.
409 protected_legacy_registration_not_deletableProtected legacy records require explicit policy review before cancellation.
403 dns_module_not_enabledDNS record management is not enabled for the partner or registrar surface.
409 backend_dns_not_supportedThe namespace backend cannot read or apply DNS records through this API.

Audit Polling

GET /poll accepts idempotency_key, command, status, domain, since, and limit filters. Use these during OT&E to prove registrar-side requests match HeadlessDomains command audits.

Poll events include the audit row id, exact registrar.channel_id, registrar channel slug, idempotency key, command status, a safe request summary, and a safe response summary for certification evidence.

GET /backend/pending lists successful registrar commands still waiting for operator or backend-worker apply, such as nameserver updates, transfer intents, and cancellations. This endpoint is read-only; backend apply remains controlled by HeadlessDomains operations.

After review, operators attach poll evidence to a named OT&E run and export the per-run evidence archive from /admin/registrar-ote-runs/<run_id>/evidence-archive.md.

GET /poll?idempotency_key=ns-001&command=update_nameservers&status=success&domain=alice.defiwallet&limit=1
GET /backend/pending?command=update_nameservers&domain=alice.defiwallet&limit=10

Current Commands

GET /statusVerify credential, channel, namespace listings, production approval, sandbox readiness, rate-limit state, and supported command scopes.
POST /sandbox/resetReset OT&E fixture domains for safe lifecycle testing.
POST /domains/checkCheck availability for a label or fully qualified SLD.
POST /domainsCreate a registration through the internal registry service.
GET /domains/{domain}Read registration status, namespace, backend references, nameservers, and lifecycle state.
POST /domains/{domain}/renewRenew a registration and debit partner Gems when applicable.
PATCH /domains/{domain}Update registrant metadata or selected lifecycle status fields.
PUT /domains/{domain}/nameserversStore desired nameserver state and audit it. Backend apply may remain pending.
GET /domains/{domain}/recordsRead supported DNS records through the registry service and backend adapter.
PUT /domains/{domain}/recordsApply supported DNS records. Sandbox mode validates and audits without backend writes.
DELETE /domains/{domain}Cancel a registration lifecycle record. This is not a hard database delete.
GET /pollRead recent registry command audit events, optionally filtered by idempotency key, command, status, domain, timestamp, or limit.
GET /backend/pendingReview pending backend apply work for registrar-visible lifecycle commands.

Not Yet OT&E

This API is the first registrar command surface. The OT&E checklist now covers command examples and certification evidence. Remaining external-testing gates are rate limits, registrar account separation, and operator approval.