Domani TLDs API

openapi: 3.2.0
info:
  title: domani.run TLDs API
  version: 1.0.0
  description: 'Domain infrastructure for AI agents. One API to search, register, and connect domain names.


    ## Authentication


    All authenticated endpoints require a Bearer token:


    ```

    Authorization: Bearer domani_sk_xxx

    ```


    Get your API key by registering:


    ```bash

    curl -X POST https://domani.run/api/auth/register \

    -H "Content-Type: application/json" \

    -d ''{"email": "you@example.com"}''

    ```


    ## Rate Limits


    Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. When rate limited (HTTP 429), check the `Retry-After` header for seconds to wait.


    ## Error Handling


    All errors return a consistent JSON envelope with `error`, `code`, `hint`, and `documentation_url` fields. Use the `code` field for programmatic handling and the `hint` field for recovery guidance.


    ## MCP Server


    A real-time MCP (Model Context Protocol) server is available at `POST /mcp` using Streamable HTTP transport. Connect any MCP-compatible agent (Claude Code, Cursor, etc.) with your Bearer token for typed tool access (search, buy, DNS, etc.).


    ## Pagination


    The `GET /api/tlds` endpoint supports `limit` and `offset` query parameters. When paginated, the response includes a `Link` header with `rel="next"` for the next page.'
  contact:
    name: domani.run
    url: https://domani.run
servers:
- url: https://domani.run
  description: Production
security:
- BearerAuth: []
tags:
- name: TLDs
paths:
  /api/tlds:
    get:
      operationId: listTlds
      summary: List the TLDs Domani sells, with pricing
      description: 'Returns the TLDs Domani sells, with registration, renewal, and transfer pricing. This is the catalog of our registrars, not every TLD that exists: some root-zone TLDs such as `gov` or `edu` cannot be registered through Domani. Each entry has a `kind`: `tld` (a TLD of the IANA root zone), `second_level` (an offering under one, such as `co.uk`), or `alt_root` (a name outside the root zone, which does not resolve in public DNS). `alt_root` entries are left out unless the `kind` parameter asks for them. Supports filtering by price range, searching by TLD name, sorting, and pagination via `limit`/`offset`. When paginated, includes a `Link` header with the next page URL. **Public endpoint** - no authentication required. Authenticated requests get higher rate limits (60/min vs 30/min).'
      tags:
      - TLDs
      security: []
      x-rateLimit:
        limit: 30
        window: 1 minute
        scope: IP address (unauthenticated), 60/min per user (authenticated)
      x-codeSamples:
      - lang: bash
        label: cURL - cheap TLDs sorted by price
        source: curl https://domani.run/api/tlds?max_price=10&sort=price
      parameters:
      - name: max_price
        in: query
        schema:
          type: number
          example: 15
        description: Maximum registration price in USD
      - name: min_price
        in: query
        schema:
          type: number
          example: 1
        description: Minimum registration price in USD
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - tld
          - price
          - renewal
          default: tld
        description: Sort field - 'tld' (alphabetical), 'price' (registration), or 'renewal'
      - name: order
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort order
      - name: search
        in: query
        schema:
          type: string
          example: dev
        description: Filter TLD names containing this string
      - name: limit
        in: query
        schema:
          type: integer
          example: 20
        description: Max results per page
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          example: 0
        description: Number of results to skip
      - name: kind
        in: query
        schema:
          type: string
          default: tld,second_level
          example: tld,second_level
        description: 'Comma-separated kinds to return: `tld`, `second_level`, `alt_root`. Default: `tld,second_level`, the entries that resolve in public DNS. `alt_root` entries (outside the IANA root zone) are returned only when asked for.'
      responses:
        '200':
          description: Paginated TLD list with pricing
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: integer
              example: 60
            X-RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: integer
              example: 57
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) when the window resets
              schema:
                type: integer
              example: 1700000000
            Link:
              description: Pagination link (rel="next") - present when more results exist
              schema:
                type: string
              example: </api/tlds?limit=20&offset=20&sort=price>; rel="next"
          content:
            application/json:
              schema:
                type: object
                properties:
                  tlds:
                    type: array
                    items:
                      $ref: '#/components/schemas/TldInfo'
                  total:
                    type: integer
                    description: Total matching TLDs (before pagination)
                  offset:
                    type: integer
                  limit:
                    type: integer
                    nullable: true
              example:
                tlds:
                - tld: xyz
                  registration: 4.04
                  renewal: 4.04
                  transfer: 4.04
                  kind: tld
                - tld: com
                  registration: 10.88
                  renewal: 13.08
                  transfer: 13.08
                  kind: tld
                - tld: co.uk
                  registration: 10.75
                  renewal: 10.75
                  transfer: 10.75
                  kind: second_level
                total: 743
                offset: 0
                limit: null
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing:
                  summary: No Authorization header
                  value:
                    error: Missing API key
                    code: MISSING_API_KEY
                    hint: 'Include ''Authorization: Bearer domani_sk_xxx'' header'
                    documentation_url: https://domani.run/llms.txt
                invalid:
                  summary: Invalid or revoked key
                  value:
                    error: Invalid API key
                    code: INVALID_API_KEY
                    hint: Check your API key or create a new one at POST /api/tokens
                    documentation_url: https://domani.run/llms.txt
                expired:
                  summary: Token has expired
                  value:
                    error: API key has expired
                    code: EXPIRED_API_KEY
                    hint: Create a new token via POST /api/tokens or run 'domani login'
                    documentation_url: https://domani.run/llms.txt
        '429':
          description: Rate limit exceeded - wait and retry
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: integer
              example: 60
            X-RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: integer
              example: 57
            X-RateLimit-Reset:
              description: Unix timestamp (seconds) when the window resets
              schema:
                type: integer
              example: 1700000000
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
              example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Rate limit exceeded
                code: RATE_LIMIT_EXCEEDED
                hint: Wait 30 seconds before retrying
                retry_after: 30
                documentation_url: https://domani.run/llms.txt
components:
  schemas:
    TldInfo:
      type: object
      properties:
        tld:
          type: string
          example: com
          description: Top-level domain without dot prefix
        registration:
          type: number
          example: 10.88
          description: First-year registration price in USD
        renewal:
          type: number
          example: 13.08
          description: Annual renewal price in USD
        transfer:
          type: number
          example: 13.08
          description: Transfer price in USD
        kind:
          type: string
          enum:
          - tld
          - second_level
          - alt_root
          example: tld
          description: 'Root-zone kind: `tld` (a TLD of the IANA root zone), `second_level` (an offering under one, such as `co.uk`), or `alt_root` (outside the root zone: does not resolve in public DNS, so search and purchase never offer it)'
      required:
      - tld
      - registration
      - renewal
      - transfer
      - kind
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
          enum:
          - MISSING_API_KEY
          - INVALID_API_KEY
          - EXPIRED_API_KEY
          - MISSING_PARAMETER
          - INVALID_DOMAIN
          - PAYMENT_REQUIRED
          - DOMAIN_UNAVAILABLE
          - RATE_LIMIT_EXCEEDED
          - USER_EXISTS
          - NOT_FOUND
          - UNKNOWN_PROVIDER
          - UNKNOWN_METHOD
          - TARGET_REQUIRED
          - INVALID_PARAMETER
          - CONTACT_REQUIRED
          - INVALID_CONTACT
          - INSUFFICIENT_SCOPE
          - SCOPE_ESCALATION
          - MAILBOX_CONFINED
          - CONFIRMATION_REQUIRED
          - OWN_SENDER
          - INVALID_SENDER_RULE
          - SENDER_RULE_NOT_FOUND
          - SENDER_RULE_LIMIT
          - SENDER_RULES_UNAVAILABLE
          - INVALID_KIND
          - MAIL_KIND_OFF
          - UNSUBSCRIBE_UNAVAILABLE
          - UNSUBSCRIBE_FAILED
          - DOMAIN_EXISTS
          - DOMAIN_NOT_ACTIVE
          - UNSUPPORTED_TLD
          - TLD_NOT_IN_PUBLIC_DNS
          - REGISTRANT_NOT_ELIGIBLE
          - NOT_AVAILABLE
          - ALREADY_REGISTERED
          - TRANSFER_NOT_ELIGIBLE
          - RENEWAL_NOT_ELIGIBLE
          - ALREADY_LISTED
          - LISTING_SOLD
          - SELF_PURCHASE
          - DESCRIPTION_TOO_LONG
          - DEAL_NOT_FOUND
          - INVALID_DEAL_STATE
          - EPP_ATTEMPTS_EXCEEDED
          - ACTIVE_DEAL_EXISTS
          - AGENT_IDENTITY_NOT_FOUND
          - AGENT_IDENTITY_ESCALATION
          - AGENT_MAILBOXES_REQUIRED
          - CREDENTIAL_REVOKE_FAILED
          - INVALID_IDEMPOTENCY_KEY
          - IDEMPOTENCY_KEY_MISMATCH
          - IDEMPOTENCY_KEY_REUSED
          - OPERATION_IN_PROGRESS
          - OPERATION_SUPERSEDED
          - INVALID_OPERATION_RECEIPT
          - WORKSPACE_ADMIN_REQUIRED
          - WORKSPACE_OWNER_REQUIRED
          - PRINCIPAL_NOT_IN_WORKSPACE
          - MAILBOX_NOT_IN_WORKSPACE
          - GROUP_NOT_IN_WORKSPACE
          - COLLECTION_NOT_IN_WORKSPACE
          - ACCESS_VERSION_CONFLICT
          - ACCESS_OFFER_INVALID
          - ACCESS_OFFER_EMAIL_MISMATCH
          - MAIL_DOMAIN_CAPACITY_EXHAUSTED
          - MAIL_PROVIDER_ERROR
          - INVALID_HTTP_ROUTE_HOSTNAME
          - INVALID_HTTP_ROUTE_UPSTREAM
          - INVALID_HTTP_ROUTE_UPSTREAM_HEADERS
          - INVALID_HTTP_ROUTE_LEASE
          - INVALID_HTTP_ROUTE_POLICY
          - INVALID_HOSTNAME_BINDING
          - HTTP_ROUTE_HOSTNAME_NOT_ALLOWED
          - HTTP_ROUTE_HOSTNAME_REQUIRED
          - HTTP_ROUTE_HOSTNAME_RESERVED
          - HTTP_ROUTE_HOSTNAME_UNAVAILABLE
          - HTTP_ROUTE_CONCURRENCY_LIMIT
          - HTTP_ROUTE_WORKSPACE_LIMIT
          - HTTP_ROUTE_DOMAIN_NOT_OWNED
          - HTTP_ROUTE_TERMINAL
          - HTTP_ROUTE_VERIFICATION_NOT_ENABLED
          - HTTP_ROUTE_VERIFICATION_REQUIRES_HTTPS
          - HTTP_ROUTE_POLICY_WITHOUT_SCOPE
          - HTTP_ROUTE_POLICY_REQUIRED
          - HTTP_ROUTE_AGENT_IDENTITY_REQUIRED
          - HTTP_ROUTE_POLICY_ESCALATION
          - HOSTNAME_BINDING_NOT_ACTIVE
          - HOSTNAME_BINDING_DNS_CONFLICT
          - HOSTNAME_BINDING_ACK_REQUIRED
          - HOSTNAME_BINDING_BROWSER_MODE_MISMATCH
          - HOSTNAME_DNS_CONFLICT
          - ZONE_READ_FAILED
          - DNS_VERSION_CONFLICT
          - UNAUTHORIZED
          - APEX_WEB_MODE_CONFLICT
          - APEX_DELEGATION_ACK_REQUIRED
          - VERIFICATION_COOLDOWN
          - VERIFICATION_SEND_FAILED
          - UPGRADE_REQUIRED
          - FREE_LIMIT_EXCEEDED
        upgrade_plan:
          type: object
          nullable: true
          description: 'On UPGRADE_REQUIRED / FREE_LIMIT_EXCEEDED: the cheapest plan that would give room for another mailbox, named from the catalog of the host the request came in on (Mailzero''s own plan on the mail host, Domani''s elsewhere). null when no plan in that catalog has more room.'
          properties:
            key:
              type: string
            name:
              type: string
            priceUsd:
              type: number
            mailboxes:
              type: integer
              nullable: true
        plan_limit:
          type: integer
          nullable: true
          description: 'On UPGRADE_REQUIRED / FREE_LIMIT_EXCEEDED: the current plan''s own mailbox limit (0 when the plan includes none, null when unlimited), so callers can tell a plan without mailboxes from a plan whose mailboxes are all in use.'
        hint:
          type: string
          description: Actionable recovery guidance for the caller
        fix_command:
          type: string
          description: CLI command to resolve the error (e.g. 'domani login', 'domani billing'). Present in CLI --json output.
        documentation_url:
          type: string
          format: uri
          description: Link to relevant documentation
        setup_url:
          type: string
          format: uri
          description: URL to resolve the issue (e.g. add payment method)
        fix_url:
          type: string
          format: uri
          description: URL to resolve the issue (alias for setup_url in CLI --json output)
        retry_after:
          type: integer
          description: Seconds until retry is allowed (present on 429 responses)
        retry_after_minutes:
          type: integer
          description: Minutes until another verification email may be requested
        retryable:
          type: boolean
          description: Whether retrying after the external condition changes is safe
      required:
      - error
      - code
      - documentation_url
      example:
        error: Missing API key
        code: MISSING_API_KEY
        hint: 'Include ''Authorization: Bearer domani_sk_xxx'' header'
        documentation_url: https://domani.run/llms.txt
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: domani_sk_xxx
      description: 'API key obtained by signing in (POST /api/auth/register starts email verification; a CLI or agent gets the key itself via the device-login flow, POST /api/auth/cli then GET /api/auth/cli/poll). Include as: `Authorization: Bearer domani_sk_xxx`. Keys use the prefix `domani_sk_` followed by 32 random characters.'
externalDocs:
  description: Interactive API Reference
  url: https://domani.run/docs