Domani Referrals API

openapi: 3.2.0
info:
  title: domani.run Referrals 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: Referrals
paths:
  /api/referrals:
    get:
      operationId: getReferrals
      summary: Get referral earnings and history
      description: Returns your unique referral code, commission rate (20%), earnings breakdown (total, paid, pending), and a history of all referred purchases. Share your referral code with others - when they register with your code (via the `ref` parameter), you earn a commission on all their future domain purchases automatically.
      tags:
      - Referrals
      x-rateLimit:
        limit: 60
        window: 1 minute
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl https://domani.run/api/referrals \\\n  -H \"Authorization: Bearer domani_sk_xxx\""
      responses:
        '200':
          description: Referral code, earnings, and history
          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
          content:
            application/json:
              schema:
                type: object
                properties:
                  referral_code:
                    type: string
                    description: Your unique referral code to share
                  referral_rate:
                    type: integer
                    description: Commission percentage (currently 20%)
                  total_earned_cents:
                    type: integer
                    description: Total earnings in cents
                  total_paid_cents:
                    type: integer
                    description: Total paid out in cents
                  total_pending_cents:
                    type: integer
                    description: Pending payout in cents
                  referrals:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        domains:
                          type: array
                          items:
                            type: string
                        earned_cents:
                          type: integer
                        paid_out:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
              example:
                referral_code: x7k9m2
                referral_rate: 20
                total_earned_cents: 400
                total_paid_cents: 200
                total_pending_cents: 200
                referrals:
                - id: cm5ref001
                  domains:
                  - friend-site.com
                  earned_cents: 200
                  paid_out: true
                  created_at: '2025-01-20T10:00:00.000Z'
                - id: cm5ref002
                  domains:
                  - another.dev
                  earned_cents: 200
                  paid_out: false
                  created_at: '2025-02-10T15:30:00.000Z'
        '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:
    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