Cheapest Domains Availability Batch API

openapi: 3.2.0
info:
  title: Cheapest Domains public Availability Batch API
  version: 1.13.0
  description: Lowest standard prices among connected registrars with saved offers matching the query, including labeled samples and labeled registrar API rates; offers that couldn’t be refreshed for a day stay, with their age, until a newer catalog replaces them. Coverage is not the whole market. Public GET-only research access, no authentication. Exact-name availability has a separate provider-scoped endpoint. No purchase, renewal, transfer, or account operations. Query current prices instead of relying on remembered values.
servers:
- url: https://www.cheapest.domains
security: []
tags:
- name: Availability Batch
paths:
  /api/v1/availability-batch:
    get:
      operationId: check_availability_batch
      summary: Check a name across extensions
      description: Check one name across up to 20 extensions, reusing shared evidence. Enrichment stops once availability is known, so premium can remain null. Partial failures keep the answers received plus retry guidance, without automatic retries. cachedOnly makes no provider calls. No selected-registrar fallback, fresh mode, prices or purchases. Provider work per call is bounded to one Cloudflare batch, one packed Name.com batch and three sequential fallback names through Gandi and Fastly, using the same pipeline as the website list.
      security: []
      parameters:
      - name: name
        in: query
        required: true
        description: One ASCII domain label without the extension, such as myproject. Price and link tools only build links from it; availability and popularity tools send the exact domain to their providers.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$
          maxLength: 63
          description: One ASCII domain label without the extension, such as myproject. Price and link tools only build links from it; availability and popularity tools send the exact domain to their providers.
      - name: tlds
        in: query
        required: true
        description: One to 20 distinct ASCII top-level extensions separated by commas, for the same name. Optional leading dots are accepted. No whole-catalog scans.
        schema:
          type: string
          maxLength: 1299
          description: One to 20 distinct ASCII top-level extensions separated by commas, for the same name. Optional leading dots are accepted. No whole-catalog scans.
      - name: cachedOnly
        in: query
        required: false
        description: Return only existing fresh availability evidence, without provider calls, lookup admission, claims or retries. Cache misses remain Not confirmed.
        schema:
          type: boolean
          default: false
          description: Return only existing fresh availability evidence, without provider calls, lookup admission, claims or retries. Cache misses remain Not confirmed.
      responses:
        '200':
          description: Success. Inspect coverage, stale flags, minimum terms and pagination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityBatch'
        '400':
          description: Invalid, repeated, unknown, or incompatible parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint, covered TLD, or connected registrar not found. Not a domain availability result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Request budget or concurrency limit reached. Anonymous calls spend weighted read units: 120 units/minute (burst 30) and 3,000/UTC day per network bucket, within a shared 600/minute (burst 120) and 30,000/UTC-day site-wide cap. Price searches rank the whole saved catalog and cost 10 units each; extension, registrar-coverage, estimate and registrar-link endpoints read one extension or source metadata and cost 1 unit, like other requests. Responses served from the CDN cache spend nothing. Each availability or popularity lookup spends 1 unit more plus one lookup from a separate allowance of 10 lookups/minute (burst 4), 300/UTC day and 3,000 per aligned 32-day window. Shared networks can share a bucket, and provider concurrency limits can also answer 429. Wait for the Retry-After seconds before retrying; do not poll.'
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Fresh pricing unavailable. Retry after 60 seconds; inspect registrar coverage.
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Availability Batch
components:
  schemas:
    ServiceInformation:
      type: object
      required:
      - name
      - url
      - setupUrl
      - pluginUrl
      description: Cheapest Domains identity and optional setup links, separate from upstream evidence. Does not establish client installation or provider health.
      properties:
        name:
          const: Cheapest Domains
        url:
          type: string
          format: uri
        setupUrl:
          type: string
          format: uri
        pluginUrl:
          type: string
          format: uri
    AvailabilityBatch:
      type: object
      required:
      - apiVersion
      - service
      - results
      - unconfirmedDomains
      - cachedOnly
      properties:
        apiVersion:
          type: string
        service:
          $ref: '#/components/schemas/ServiceInformation'
        cachedOnly:
          type: boolean
        results:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/AvailabilityEvidence'
        unconfirmedDomains:
          type: array
          maxItems: 20
          items:
            type: string
          description: Domains with unknown availability, not taken domains. Premium must be inspected separately even when this list is empty.
        error:
          type: object
          required:
          - code
          - retryAfterSeconds
          description: 'Partial failure: retain successful facts and wait before another explicit request. A confirmed Cloudflare-specific rate denial may continue through admitted fallback providers. Caller or shared-storage failure with no returned results uses the ordinary HTTP/MCP error envelope.'
          properties:
            code:
              type: string
            retryAfterSeconds:
              type: number
              minimum: 0
            domains:
              type: array
              maxItems: 20
              items:
                type: string
              description: When present, only these domains have a paused fallback.
    AvailabilityEvidence:
      type: object
      required:
      - domain
      - status
      - reason
      - message
      - provider
      - checkedAt
      - expiresAt
      properties:
        availability:
          enum:
          - available
          - unavailable
          - unknown
          description: Registration status; independent of premium classification.
        premium:
          type:
          - boolean
          - 'null'
          description: Null means not confirmed, never standard tier.
        registrar:
          type: string
        attempts:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/AvailabilityAttempt'
        fallback:
          type: object
          required:
          - registrar
          - state
          - reason
          properties:
            registrar:
              type: string
            state:
              enum:
              - used
              - unavailable
            reason:
              type: string
        domain:
          type: string
        status:
          type: string
          enum:
          - available
          - unavailable
          - premium
          - unsupported
          - unknown
        reason:
          type: string
        message:
          type: string
        provider:
          type: object
          required:
          - id
          - name
          - documentation
          properties:
            id:
              type: string
            name:
              type: string
            documentation:
              type: string
              format: uri
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Successful provider response time; null when no reliable result was obtained.
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Recheck after this time; never a reservation or guarantee until expiry.
        listEnrichmentComplete:
          type: boolean
          description: 'Batch results: true when availability is known or every configured fallback stage has answered for this name. False means a later explicit request may add facts; it never means taken.'
    AvailabilityAttempt:
      type: object
      required:
      - provider
      - availability
      - premium
      - reason
      - checkedAt
      - expiresAt
      properties:
        provider:
          type: object
          required:
          - id
          - name
          - documentation
          properties:
            id:
              type: string
            name:
              type: string
            documentation:
              type: string
              format: uri
        availability:
          enum:
          - available
          - unavailable
          - unknown
        premium:
          type:
          - boolean
          - 'null'
        reason:
          type: string
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        outcome:
          enum:
          - answered
          - failed
          - pending
          description: Whether this stage returned an answer, failed before confirming evidence, or is still in progress. Optional for older responses.
        retryAfterSeconds:
          type: number
          minimum: 0
          description: Suggested wait after a failed stage; never an evidence lifetime.
    Error:
      type: object
      required:
      - apiVersion
      - error
      properties:
        apiVersion:
          type: string
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            retryAfterSeconds:
              type: number
              minimum: 0
externalDocs:
  description: Human and AI integration guide
  url: https://www.cheapest.domains/developers