{
    "openapi": "3.0.3",
    "info": {
        "title": "domain.pay API",
        "version": "1.0.0",
        "description": "Public HTTP API for checking .pay availability, searching the curated catalogue, placing pre-orders against a saved card, managing saved cards + webhooks, and (with approval) pulling the DNS zone file, premium catalogue, and registered-names data.\n\n## Authentication\nSend an API key as a Bearer token: `Authorization: Bearer dpk_live_<selector>_<secret>`. Create + manage keys at `/account/settings` (the full key is shown once). A logged-in browser session is also accepted; session-authenticated writes additionally require an `X-CSRF-Token` header (Bearer requests do not).\n\n## Scopes\n- `domain.check` (50/sec) — Check a single .pay domain — availability + pricing\n- `catalog.search` (30/min) — AI keyword search against the curated catalog\n- `orders.read` (60/min) — List + read the account's own orders\n- `orders.write` (10/min) — Create a pre-order against a saved payment method\n- `payment_methods.read` (20/min) — List saved cards (Stripe payment methods)\n- `payment_methods.write` (20/min) — Add (SetupIntent) + remove saved cards\n- `account.read` (60/min) — Read account profile: email, role, vip_tier, granted scopes\n- `webhooks.read` (20/min) — List configured webhook endpoints\n- `webhooks.write` (10/min) — Create + delete webhook endpoints\n- `zone_file.download` (24/day, restricted) — Download the full daily .pay DNS zone-file snapshot\n- `premium.list` (60/min, restricted) — Paginated registry premium catalogue (incl. reserved/blocked)\n- `registered.list` (60/min, restricted) — Paginated registered .pay names (from the DNS zone file) + AI brand context\n\nRestricted scopes are double-gated: the key must list the scope **and** the account must have an admin-approved grant (apply at `/account/settings`).\n\n## Conventions\nTimes are UTC. Money is USD decimal. Every error echoes a `request_id`.",
        "contact": {
            "name": "domain.pay support",
            "url": "https://domain.pay/contact"
        },
        "license": {
            "name": "Proprietary — domain.pay Terms of Service",
            "url": "https://domain.pay/terms"
        }
    },
    "servers": [
        {
            "url": "https://domain.pay/api/v1",
            "description": ".pay zone"
        },
        {
            "url": "https://domain.latino/api/v1",
            "description": ".latino zone"
        },
        {
            "url": "https://domain.dot/api/v1",
            "description": ".dot zone"
        }
    ],
    "tags": [
        {
            "name": "Account",
            "description": "Profile + effective scopes."
        },
        {
            "name": "Domains",
            "description": "Availability + pricing checks."
        },
        {
            "name": "Catalog",
            "description": "Curated catalogue search."
        },
        {
            "name": "Orders",
            "description": "Read orders + place programmatic pre-orders."
        },
        {
            "name": "Payment methods",
            "description": "Saved cards (Stripe)."
        },
        {
            "name": "Webhooks",
            "description": "Register HTTPS endpoints for pushed events."
        },
        {
            "name": "Restricted",
            "description": "Approval-gated bulk data."
        }
    ],
    "security": [
        {
            "ApiKeyBearer": []
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyBearer": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "dpk_<env>_<selector>_<secret>",
                "description": "API key as a Bearer token. `env` is `live` or `test`; `selector` is 16 hex; `secret` is 48 hex. First-party session cookies are also accepted (session writes need `X-CSRF-Token`)."
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Missing or invalid credential (`unauthorized` / `invalid_key`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The key lacks the required scope (`scope_required`), the restricted scope is not granted (`access_not_granted`), or a session write is missing `X-CSRF-Token` (`csrf_required`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "No such resource / endpoint (`not_found`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "AccountLocked": {
                "description": "The account is locked (`account_locked`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Rate limit exceeded (`rate_limited`). A `Retry-After` header gives the seconds to wait.",
                "headers": {
                    "Retry-After": {
                        "description": "Seconds until the limit resets.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "ServerError": {
                "description": "Unexpected server error (`server_error`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "description": "Uniform error envelope returned by every 4xx/5xx response.",
                "required": [
                    "error",
                    "message",
                    "request_id"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "Stable machine code, e.g. `scope_required`."
                    },
                    "message": {
                        "type": "string",
                        "description": "Human-readable explanation."
                    },
                    "request_id": {
                        "type": "string",
                        "example": "req_ab12cd34ef567890",
                        "description": "`req_` + 16 hex; quote it in support requests."
                    },
                    "scope": {
                        "type": "string",
                        "nullable": true,
                        "description": "On scope errors, the scope that was required."
                    },
                    "retry_after": {
                        "type": "integer",
                        "nullable": true,
                        "description": "On `rate_limited`, seconds to wait."
                    },
                    "limit": {
                        "type": "integer",
                        "nullable": true
                    },
                    "window_seconds": {
                        "type": "integer",
                        "nullable": true
                    }
                }
            },
            "Account": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "account"
                    },
                    "account": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "email": {
                                "type": "string"
                            },
                            "role": {
                                "type": "string"
                            },
                            "display_name": {
                                "type": "string",
                                "nullable": true
                            },
                            "company_name": {
                                "type": "string",
                                "nullable": true
                            },
                            "country": {
                                "type": "string",
                                "nullable": true
                            },
                            "preferred_locale": {
                                "type": "string",
                                "nullable": true
                            },
                            "account_status": {
                                "type": "string"
                            },
                            "created_at": {
                                "type": "string",
                                "nullable": true,
                                "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                "example": "2026-07-01 21:41:21"
                            }
                        }
                    },
                    "auth": {
                        "type": "object",
                        "properties": {
                            "via": {
                                "type": "string",
                                "enum": [
                                    "api_key",
                                    "session"
                                ]
                            },
                            "api_key_id": {
                                "type": "integer",
                                "nullable": true
                            },
                            "effective_scopes": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "granted_restricted": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "request_id": {
                        "type": "string"
                    }
                }
            },
            "DomainCheck": {
                "type": "object",
                "description": "Availability + pricing for one name, mirroring the website result card. Field set varies by state (available / premium / reserved / registered); common fields are shown, additional fields may be present.",
                "additionalProperties": true,
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "domain_check"
                    },
                    "input": {
                        "type": "string"
                    },
                    "label": {
                        "type": "string",
                        "nullable": true
                    },
                    "domain": {
                        "type": "string",
                        "nullable": true
                    },
                    "valid": {
                        "type": "boolean"
                    },
                    "error": {
                        "type": "string",
                        "nullable": true,
                        "description": "Set when `valid` is false, e.g. `invalid_format`."
                    }
                }
            },
            "CatalogSearch": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "catalog_search"
                    },
                    "keyword": {
                        "type": "string"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "results": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "domain": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "result_state": {
                                    "type": "string"
                                },
                                "premium": {
                                    "type": "boolean"
                                },
                                "price_usd": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "theme": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "fintech_score": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "rationale": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "detail_url": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "Order": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "domain": {
                        "type": "string"
                    },
                    "lead_type": {
                        "type": "string"
                    },
                    "flow_type": {
                        "type": "string"
                    },
                    "payment_status": {
                        "type": "string"
                    },
                    "payment_method": {
                        "type": "string",
                        "nullable": true
                    },
                    "amount_usd": {
                        "type": "number",
                        "nullable": true
                    },
                    "estimated_total_usd": {
                        "type": "number",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "nullable": true,
                        "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                        "example": "2026-07-01 21:41:21"
                    },
                    "paid_at": {
                        "type": "string",
                        "nullable": true,
                        "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                        "example": "2026-07-01 21:41:21"
                    }
                }
            },
            "OrderList": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "order_list"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "limit": {
                        "type": "integer"
                    },
                    "offset": {
                        "type": "integer"
                    },
                    "orders": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Order"
                        }
                    }
                }
            },
            "OrderDetail": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "order"
                    },
                    "order": {
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Order"
                            },
                            {
                                "type": "object",
                                "properties": {
                                    "trademark_name": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "trademark_number": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "has_tmch": {
                                        "type": "boolean",
                                        "nullable": true
                                    },
                                    "messages": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "sender_role": {
                                                    "type": "string",
                                                    "enum": [
                                                        "customer",
                                                        "manager",
                                                        "admin",
                                                        "system"
                                                    ]
                                                },
                                                "body": {
                                                    "type": "string"
                                                },
                                                "created_at": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                                    "example": "2026-07-01 21:41:21"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        ]
                    }
                }
            },
            "OrderCreateRequest": {
                "type": "object",
                "required": [
                    "domain",
                    "payment_method_id"
                ],
                "properties": {
                    "domain": {
                        "type": "string",
                        "example": "acme.pay"
                    },
                    "payment_method_id": {
                        "type": "string",
                        "pattern": "^pm_[A-Za-z0-9]+$",
                        "example": "pm_1Nw2x3Ab4Cd5Ef"
                    },
                    "message": {
                        "type": "string",
                        "nullable": true,
                        "description": "Optional note attached to the order."
                    }
                }
            },
            "OrderCreated": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "order"
                    },
                    "order": {
                        "$ref": "#/components/schemas/Order"
                    },
                    "payment": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "example": "succeeded"
                            },
                            "payment_intent_id": {
                                "type": "string"
                            },
                            "amount_usd": {
                                "type": "number"
                            }
                        }
                    }
                }
            },
            "OrderPaymentActionRequired": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "order"
                    },
                    "order": {
                        "$ref": "#/components/schemas/Order"
                    },
                    "payment": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "example": "requires_action"
                            },
                            "error": {
                                "type": "string",
                                "example": "authentication_required"
                            },
                            "message": {
                                "type": "string"
                            },
                            "client_secret": {
                                "type": "string",
                                "description": "Complete SCA on-session with Stripe.js using this."
                            },
                            "payment_intent_id": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "OrderPaymentFailed": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "order"
                    },
                    "order": {
                        "$ref": "#/components/schemas/Order"
                    },
                    "payment": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "example": "failed"
                            },
                            "error": {
                                "type": "string",
                                "example": "card_declined"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "PaymentMethodList": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "payment_method_list"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "payment_methods": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "example": "pm_1Nw2x3Ab4Cd5Ef"
                                },
                                "brand": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "last4": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "exp_month": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "exp_year": {
                                    "type": "integer",
                                    "nullable": true
                                }
                            }
                        }
                    }
                }
            },
            "SetupIntent": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "setup_intent"
                    },
                    "client_secret": {
                        "type": "string"
                    },
                    "setup_intent_id": {
                        "type": "string"
                    },
                    "publishable_key": {
                        "type": "string"
                    }
                }
            },
            "DeletedPaymentMethod": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "payment_method"
                    },
                    "id": {
                        "type": "string"
                    },
                    "deleted": {
                        "type": "boolean",
                        "example": true
                    }
                }
            },
            "WebhookList": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "webhook_list"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "webhooks": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "url": {
                                    "type": "string"
                                },
                                "events": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "enabled": {
                                    "type": "boolean"
                                },
                                "failure_count": {
                                    "type": "integer"
                                },
                                "last_attempt_at": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                    "example": "2026-07-01 21:41:21"
                                },
                                "last_success_at": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                    "example": "2026-07-01 21:41:21"
                                },
                                "created_at": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                    "example": "2026-07-01 21:41:21"
                                }
                            }
                        }
                    }
                }
            },
            "WebhookCreateRequest": {
                "type": "object",
                "required": [
                    "url"
                ],
                "properties": {
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://example.com/hook",
                        "description": "HTTPS only; must not resolve to a private/loopback host; max 512 chars."
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Exact names, family wildcards (`order.*`), or `*`. Defaults to `[\"*\"]`.",
                        "example": [
                            "order.*",
                            "payment.succeeded"
                        ]
                    }
                }
            },
            "WebhookCreated": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "webhook"
                    },
                    "id": {
                        "type": "integer"
                    },
                    "url": {
                        "type": "string"
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "enabled": {
                        "type": "boolean",
                        "example": true
                    },
                    "signing_secret": {
                        "type": "string",
                        "description": "Shown ONCE. 64 hex chars. Verify deliveries by recomputing HMAC-SHA256 over the raw body."
                    }
                }
            },
            "DeletedWebhook": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "webhook"
                    },
                    "id": {
                        "type": "integer"
                    },
                    "deleted": {
                        "type": "boolean",
                        "example": true
                    }
                }
            },
            "ZoneFile": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "zone_file"
                    },
                    "description": {
                        "type": "string"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "limit": {
                        "type": "integer"
                    },
                    "offset": {
                        "type": "integer"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "domains": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "PremiumList": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "premium_list"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "limit": {
                        "type": "integer"
                    },
                    "offset": {
                        "type": "integer"
                    },
                    "status": {
                        "type": "string",
                        "nullable": true
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "label": {
                                    "type": "string"
                                },
                                "domain": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "tier": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "registration_price_usd": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "renewal_price_usd": {
                                    "type": "number",
                                    "nullable": true
                                }
                            }
                        }
                    }
                }
            },
            "RegisteredList": {
                "type": "object",
                "properties": {
                    "object": {
                        "type": "string",
                        "example": "registered_list"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "limit": {
                        "type": "integer"
                    },
                    "offset": {
                        "type": "integer"
                    },
                    "note": {
                        "type": "string"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "domain": {
                                    "type": "string"
                                },
                                "brand": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "context": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "confidence": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "context_at": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "UTC datetime, MySQL format `Y-m-d H:i:s` (NOT RFC3339 — no `T` separator, no timezone suffix).",
                                    "example": "2026-07-01 21:41:21"
                                }
                            }
                        }
                    }
                }
            },
            "WebhookEventEnvelope": {
                "type": "object",
                "description": "The JSON body POSTed to your registered webhook URL. Headers: `X-Domain-Pay-Event`, `X-Domain-Pay-Delivery`, and `X-Domain-Pay-Signature: sha256=<HMAC-SHA256(raw_body, signing_secret)>`.",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "evt_0123456789abcdef01234567"
                    },
                    "event": {
                        "type": "string",
                        "enum": [
                            "order.created",
                            "order.status_changed",
                            "payment.succeeded",
                            "payment.failed",
                            "payment.refunded",
                            "appraisal.completed"
                        ]
                    },
                    "created": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "data": {
                        "type": "object",
                        "description": "Event payload. All events include `order`; `appraisal.completed` additionally includes `appraisal`.",
                        "additionalProperties": true,
                        "properties": {
                            "order": {
                                "type": "object",
                                "properties": {
                                    "id": {
                                        "type": "integer"
                                    },
                                    "domain": {
                                        "type": "string"
                                    },
                                    "requested_domain": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "flow_type": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "payment_status": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "amount_usd": {
                                        "type": "number",
                                        "nullable": true
                                    }
                                }
                            },
                            "appraisal": {
                                "type": "object",
                                "properties": {
                                    "reasonable_value": {
                                        "type": "number"
                                    },
                                    "lowest_value": {
                                        "type": "number"
                                    },
                                    "highest_value": {
                                        "type": "number"
                                    },
                                    "currency": {
                                        "type": "string"
                                    },
                                    "url": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/account": {
            "get": {
                "tags": [
                    "Account"
                ],
                "operationId": "getAccount",
                "summary": "Current account + effective scopes",
                "description": "Returns the caller's profile, the scopes effective for this key, and any granted restricted scopes. Also reachable at `GET /`.\n\n**Scope:** `account.read` · **Rate limit:** 60/min",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Account"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "423": {
                        "$ref": "#/components/responses/AccountLocked"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/check-domain": {
            "post": {
                "tags": [
                    "Domains"
                ],
                "operationId": "checkDomain",
                "summary": "Check availability + pricing for a name",
                "description": "Returns availability and pricing for a single .pay name (available / premium / reserved / registered). **This is a fast, DB-only lookup** (zone-file snapshot + cached registry results) — it does not make a live registry call, so a name that registered in just the last few minutes may still show as available here. The authoritative, live re-check happens when you actually place the order (`POST /orders`), which will correctly reject a name that turns out to be taken.\n\n**Scope:** `domain.check` · **Rate limit:** 50/sec",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "domain"
                                ],
                                "properties": {
                                    "domain": {
                                        "type": "string",
                                        "example": "acme.pay",
                                        "description": "The name to check. `query` is accepted as an alias."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DomainCheck"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`bad_request` — no domain supplied.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/catalog/search": {
            "post": {
                "tags": [
                    "Catalog"
                ],
                "operationId": "searchCatalog",
                "summary": "Keyword search the curated catalogue",
                "description": "Keyword search over the curated catalogue (orderable names only). Cheap DB search — no paid AI generation.\n\n**Scope:** `catalog.search` · **Rate limit:** 30/min",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "q"
                                ],
                                "properties": {
                                    "q": {
                                        "type": "string",
                                        "example": "wallet",
                                        "description": "`keyword` is accepted as an alias."
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "default": 25,
                                        "minimum": 1,
                                        "maximum": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CatalogSearch"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/orders": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "operationId": "listOrders",
                "summary": "List the account's orders",
                "description": "Lists the account's orders, newest first.\n\n**Scope:** `orders.read` · **Rate limit:** 60/min",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filter by payment status."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "minimum": 1,
                            "maximum": 100
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0,
                            "minimum": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderList"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            },
            "post": {
                "tags": [
                    "Orders"
                ],
                "operationId": "createOrder",
                "summary": "Create a pre-order + charge a saved card",
                "description": "Creates a pre-order and charges a saved card off-session. The order email is forced to the key/session account's own verified address. **Send an `Idempotency-Key` header** (any UUID) — retrying with the same key replays the original outcome verbatim (`Idempotent-Replayed: true`), so a timeout-retry never double-charges. Test-mode keys (`dpk_test_…`) are rejected with `test_key_forbidden`.\n\n**Scope:** `orders.write` · **Rate limit:** 10/min",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        },
                        "description": "Strongly recommended. Same key + same body → replayed response. Same key + different body → `422 idempotency_key_reused`. In-flight → `409 request_in_progress`."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderCreateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order created + card charged.",
                        "headers": {
                            "Idempotent-Replayed": {
                                "description": "`true` when this is a replay of a prior identical request.",
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderCreated"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`invalid_request` / `invalid_domain` — bad or missing parameters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "description": "Payment needs SCA (`requires_action`) or failed (`card_declined` / `payment_failed`). The order exists.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/OrderPaymentActionRequired"
                                        },
                                        {
                                            "$ref": "#/components/schemas/OrderPaymentFailed"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "`scope_required`, `csrf_required`, or `test_key_forbidden` (a test key tried to charge a real card).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`domain_not_orderable` (name unavailable) or `request_in_progress` (idempotency key in flight).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`idempotency_key_reused` — the same key was used with different parameters.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "description": "`availability_check_failed` — the registry availability check failed; retry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/orders/{id}": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "operationId": "getOrder",
                "summary": "One order + its customer message thread",
                "description": "Returns one order and its customer-visible message thread. Staff-internal notes are never exposed.\n\n**Scope:** `orders.read` · **Rate limit:** 60/min",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderDetail"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`bad_request` — invalid id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/account/payment-methods": {
            "get": {
                "tags": [
                    "Payment methods"
                ],
                "operationId": "listPaymentMethods",
                "summary": "List saved cards",
                "description": "Lists the account's saved cards. Card data lives at Stripe — we never store it.\n\n**Scope:** `payment_methods.read` · **Rate limit:** 20/min",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaymentMethodList"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "503": {
                        "description": "`stripe_unavailable` — Stripe not configured.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Payment methods"
                ],
                "operationId": "createSetupIntent",
                "summary": "Start a SetupIntent to add a card",
                "description": "Returns a Stripe SetupIntent `client_secret`; confirm it client-side with Stripe.js (`confirmCardSetup`) to attach a card.\n\n**Scope:** `payment_methods.write` · **Rate limit:** 20/min",
                "responses": {
                    "200": {
                        "description": "SetupIntent created (the handler returns 200, not 201).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SetupIntent"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "502": {
                        "description": "`stripe_error` — SetupIntent creation failed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "`stripe_unavailable` — Stripe not configured.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/account/payment-methods/{id}": {
            "delete": {
                "tags": [
                    "Payment methods"
                ],
                "operationId": "deletePaymentMethod",
                "summary": "Remove a saved card",
                "description": "Detaches a saved card (ownership-checked).\n\n**Scope:** `payment_methods.write` · **Rate limit:** 20/min",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^pm_[A-Za-z0-9]+$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeletedPaymentMethod"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`bad_request` — invalid payment-method id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/webhooks": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "listWebhooks",
                "summary": "List webhook endpoints",
                "description": "Lists the account's webhook endpoints. The signing secret is never returned after creation.\n\n**Scope:** `webhooks.read` · **Rate limit:** 20/min",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookList"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "createWebhook",
                "summary": "Register a webhook endpoint",
                "description": "Registers an HTTPS endpoint. The response includes a `signing_secret` **shown once**. Max 20 endpoints per account.\n\n**Scope:** `webhooks.write` · **Rate limit:** 10/min",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WebhookCreateRequest"
                            }
                        }
                    }
                },
                "callbacks": {
                    "event": {
                        "{$request.body#/url}": {
                            "post": {
                                "summary": "Event delivery to your endpoint",
                                "description": "We POST this envelope to your registered `url` when a subscribed event fires. Verify the `X-Domain-Pay-Signature` header (HMAC-SHA256 of the raw body with your signing secret) before trusting it. Non-2xx or timeout is retried with exponential backoff (1 min → 24 h, 6 attempts); 5 consecutive dead deliveries auto-disable the endpoint.",
                                "requestBody": {
                                    "required": true,
                                    "content": {
                                        "application/json": {
                                            "schema": {
                                                "$ref": "#/components/schemas/WebhookEventEnvelope"
                                            }
                                        }
                                    }
                                },
                                "responses": {
                                    "2XX": {
                                        "description": "Any 2xx acknowledges receipt."
                                    },
                                    "4XX": {
                                        "description": "Any non-2xx (or a timeout) is treated as a failed delivery and retried with backoff."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WebhookCreated"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`invalid_request` — bad URL (non-HTTPS / private host / too long) or no valid events.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "`limit_reached` — 20 endpoints already registered.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/webhooks/{id}": {
            "delete": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "deleteWebhook",
                "summary": "Delete a webhook endpoint",
                "description": "Removes an endpoint and its pending deliveries.\n\n**Scope:** `webhooks.write` · **Rate limit:** 10/min",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeletedWebhook"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`invalid_request` — invalid id.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/zone-file": {
            "get": {
                "tags": [
                    "Restricted"
                ],
                "operationId": "getZoneFile",
                "summary": "Daily .pay DNS zone-file snapshot",
                "description": "The daily .pay DNS zone-file snapshot (currently-delegated names), paginated.\n\n**Scope:** `zone_file.download` · **Rate limit:** 24/day · **Restricted** — the account also needs an approved grant for this scope",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 50000,
                            "minimum": 1,
                            "maximum": 100000
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0,
                            "minimum": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ZoneFile"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/premium": {
            "get": {
                "tags": [
                    "Restricted"
                ],
                "operationId": "listPremium",
                "summary": "Registry premium catalogue",
                "description": "Premium catalogue rows: label, status, tier, registration + renewal price.\n\n**Scope:** `premium.list` · **Rate limit:** 60/min · **Restricted** — the account also needs an approved grant for this scope",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "premium",
                                "reserved",
                                "blocked",
                                "standard"
                            ]
                        }
                    },
                    {
                        "name": "tld",
                        "in": "query",
                        "required": false,
                        "description": "Zone to list (an enabled tenant tld). Default pay.",
                        "schema": {
                            "type": "string",
                            "default": "pay"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "minimum": 1,
                            "maximum": 1000
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0,
                            "minimum": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PremiumList"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/registered": {
            "get": {
                "tags": [
                    "Restricted"
                ],
                "operationId": "listRegistered",
                "summary": "Registered .pay names + AI brand context",
                "description": "Registered .pay names with optional AI brand context. Context notes are AI guesses from the label, not ownership claims.\n\n**Scope:** `registered.list` · **Rate limit:** 60/min · **Restricted** — the account also needs an approved grant for this scope",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "minimum": 1,
                            "maximum": 1000
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0,
                            "minimum": 0
                        }
                    },
                    {
                        "name": "with_context",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "When set, only rows that have AI context."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RegisteredList"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        }
    }
}