/api/v1 — what changed

2026-05-25 · v1.0

Public launch — REST API v1

• Bearer authentication with gg_<env>_pk_… keys, prefix visible, plaintext one-time at mint.
• Stripe-style JSON envelope on every response. X-Request-Id on every response.
• Domains — list, register, search, availability, show, patch (nameservers / auto_renew / customer_id), transfer, renew.
• DNS — list / create / delete records (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA).
• SSL — list, issue (DV / OV / EV / wildcard), show, renew, reissue.
• Hosting — list, provision, show, suspend, unsuspend, rotate password.
• Billing — read-only orders + invoices with line items.
• Webhooks — subscribe, list, patch, delete, test. HMAC-SHA256 signing, exponential retry.
• Usage — 30-day daily request counts, error rate, latency.

Upcoming

Planned for v1 (additive — no client changes required)

• Signed pagination cursors (currently the cursor is an opaque row id; clients won't notice).
• Per-tenant rate-limit headers (X-RateLimit-Remaining, Retry-After).
• Idempotency-Key honoured for 24h via the api_idempotency table.
• Test-mode separation: gg_test_pk_… keys never hit external systems, webhooks carry "livemode": false.
• First-class SDKs: PHP, Node, Python, Go — generated from the OpenAPI spec.

Versioning policy

What counts as breaking

Removing a field, changing a field's type, renaming a path, or changing the semantics of an existing event — those go to /api/v2. Adding a new field, a new endpoint, or a new event name does NOT. Treat unknown JSON keys as opaque (Postel's law); we add them often.