Domani Backorders API

openapi: 3.2.0
info:
  title: domani.run Backorders 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: Backorders
paths:
  /api/backorders:
    post:
      operationId: createBackorder
      summary: Place a backorder on a taken domain
      description: 'Watches a domain that is currently registered to someone else and automatically registers it for you when it becomes available (drops) - availability is polled every few minutes, so the catch lands within minutes of the drop. You are charged only if and when the catch succeeds - no upfront fee. A price cap protects you from a registration-price spike between now and the drop.


        Requires a payment method on file (card) or `payment_method: "balance"` so the catch can be paid when it happens. Best-effort: a contested drop may be taken by a specialized drop-catcher first.'
      tags:
      - Backorders
      x-rateLimit:
        limit: 20
        window: 1 minute
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST https://domani.run/api/backorders \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\": \"taken.com\"}'"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  example: taken.com
                  description: The currently-registered domain to watch and catch on drop.
                max_price:
                  type: number
                  description: Max USD you'll pay to catch it. Defaults to the current registration price. Must be >= the current price.
                payment_method:
                  type: string
                  enum:
                  - card
                  - balance
                  description: How to pay when caught. Defaults to your preferred method.
            examples:
              simple:
                summary: Watch a domain
                value:
                  domain: taken.com
              capped:
                summary: With a price cap and balance
                value:
                  domain: taken.com
                  max_price: 25
                  payment_method: balance
      responses:
        '201':
          description: Backorder placed
          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:
                  backorder:
                    $ref: '#/components/schemas/Backorder'
                  hint:
                    type: string
        '400':
          description: Domain is available now (buy it directly), TLD unsupported, or invalid input
        '402':
          description: A payment method is required to place the backorder
        '409':
          description: You already have an active backorder on this domain, or the active-backorder limit was reached
    get:
      operationId: listBackorders
      summary: List your backorders
      description: Returns your backorders, newest first. Filter by `status` (watching, caught, failed, cancelled, expired).
      tags:
      - Backorders
      x-rateLimit:
        limit: 60
        window: 1 minute
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - watching
          - caught
          - failed
          - cancelled
          - expired
        description: Filter by status.
      responses:
        '200':
          description: Your backorders
          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:
                  backorders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Backorder'
  /api/backorders/{id}:
    get:
      operationId: getBackorder
      summary: Get a backorder
      tags:
      - Backorders
      x-rateLimit:
        limit: 60
        window: 1 minute
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Backorder ID.
      responses:
        '200':
          description: The backorder
          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:
                  backorder:
                    $ref: '#/components/schemas/Backorder'
        '404':
          description: Backorder not found
    delete:
      operationId: cancelBackorder
      summary: Cancel a backorder
      description: Stops watching a domain. Only backorders in the `watching` state can be cancelled.
      tags:
      - Backorders
      x-rateLimit:
        limit: 30
        window: 1 minute
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Backorder ID.
      responses:
        '200':
          description: Backorder cancelled
          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:
                  id:
                    type: string
                  status:
                    type: string
                  hint:
                    type: string
        '404':
          description: Backorder not found
        '409':
          description: Backorder is not in the watching state
  /api/watchlist:
    post:
      operationId: watchDomain
      summary: Follow a taken domain
      description: 'Follows a domain someone else holds, for free: no payment, no commitment. You get an alert (in the app and by email) once at each step of its lifecycle: expiring within 30 days, expired and not renewed, in redemption, pending delete (it drops in about 5 days), available again, and listed for sale. A renewal raises no alert. The step the name is at when you follow it raises no alert either.


        To register the name automatically when it drops, place a backorder (POST /api/backorders). An account follows at most 50 names.'
      tags:
      - Backorders
      x-rateLimit:
        limit: 30
        window: 1 minute
      x-codeSamples:
      - lang: bash
        label: cURL
        source: "curl -X POST https://domani.run/api/watchlist \\\n  -H \"Authorization: Bearer domani_sk_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"domain\": \"taken.com\"}'"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
                  example: taken.com
                  description: The domain to follow.
      responses:
        '200':
          description: Already following the domain
          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:
                  watch:
                    $ref: '#/components/schemas/Watch'
        '201':
          description: Now following the domain
          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:
                  watch:
                    $ref: '#/components/schemas/Watch'
        '400':
          description: Invalid domain
        '403':
          description: The account already follows 50 names (WATCHLIST_LIMIT)
    get:
      operationId: listWatches
      summary: List the domains you follow
      description: Returns the domains you follow, newest first, with where each one stands and your active backorder on it, if any.
      tags:
      - Backorders
      x-rateLimit:
        limit: 60
        window: 1 minute
      responses:
        '200':
          description: The domains you follow
          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:
                  watches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Watch'
  /api/watchlist/{domain}:
    delete:
      operationId: unwatchDomain
      summary: Stop following a domain
      description: Stops the alerts on a followed domain. A backorder on it is not affected.
      tags:
      - Backorders
      x-rateLimit:
        limit: 30
        window: 1 minute
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        description: The followed domain, e.g. taken.com.
      responses:
        '200':
          description: No longer following the domain
          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:
                  deleted:
                    type: boolean
        '404':
          description: You do not follow this domain (WATCH_NOT_FOUND)
components:
  schemas:
    Backorder:
      type: object
      description: A watch on a taken domain that auto-registers it when it drops
      properties:
        id:
          type: string
        domain:
          type: string
          example: taken.com
        status:
          type: string
          enum:
          - watching
          - caught
          - failed
          - cancelled
          - expired
        payment_method:
          type: string
          enum:
          - card
          - balance
        max_price:
          type: number
          description: Max USD you'll pay to catch it
        currency:
          type: string
          example: USD
        domain_expires:
          type: string
          format: date-time
          nullable: true
          description: Current registration's expiry (informational)
        last_checked:
          type: string
          format: date-time
          nullable: true
        attempts:
          type: integer
          description: Number of availability checks performed
        caught_at:
          type: string
          format: date-time
          nullable: true
        registered_domain_id:
          type: string
          nullable: true
          description: ID of the Domain created when caught
        failure_reason:
          type: string
          nullable: true
          enum:
          - price_cap
          - registration_race
          - marketplace_listing
          - payment
          - registrar
          - unavailable
          - unexpected
          - unspecified
          description: Stable, language-independent failure code. Internal registrar prose is never returned.
        expires_at:
          type: string
          format: date-time
          description: When the watch window ends
        created_at:
          type: string
          format: date-time
    Watch:
      type: object
      description: 'A taken domain you follow for free: an alert at each step until it drops'
      properties:
        id:
          type: string
        domain:
          type: string
          example: taken.com
        created_at:
          type: string
          format: date-time
        phase:
          type: string
          enum:
          - registered
          - expiring
          - expired
          - redemption
          - pending_delete
          - available
          - unknown
          description: 'Where the name stands: registered, expiring (within 30 days), expired (not renewed yet), redemption (only the last owner can recover it), pending_delete (drops in about 5 days), available, or unknown (the registry has not answered yet).'
        registered_at:
          type: string
          format: date-time
          nullable: true
          description: When the name was first registered, when the registry publishes it
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When the current registration expires
        for_sale:
          type: object
          nullable: true
          description: Set when the name is listed for sale on a marketplace
          properties:
            source:
              type: string
              example: Afternic
            url:
              type: string
            price:
              type: number
              nullable: true
              description: Asking price in USD, when known
        last_checked_at:
          type: string
          format: date-time
          nullable: true
        backorder_id:
          type: string
          nullable: true
          description: Your active backorder on this name, if any
  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