Cheapest Domains Availability API

openapi: 3.2.0
info:
  title: Cheapest Domains public Availability 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
paths:
  /api/v1/availability:
    get:
      operationId: check_availability
      summary: Check domain availability
      description: 'Check one exact domain. Cloudflare answers first; configured fallbacks, then an optional selected registrar, run only for missing facts; a taken name ends the chain. Returns separate availability and nullable premium facts, provider attempts and check times; null premium is unconfirmed, not standard tier. Recheck after expiresAt (5 min; up to 30 days if taken). No prices, purchase or reservation. Fallback order is Name.com, then Gandi, then Fastly Precise, each only when configured and at most once. A registrar argument adds one final call only when its connected adapter can confirm a missing fact and it was not already used as a fallback: Gandi fallback already covers Gandi, and Vercel confirms availability only. The chain stops once availability and premium are both confirmed.'
      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: tld
        in: query
        required: true
        description: One covered ASCII top-level extension, such as com or .com. Multi-part suffixes and IDNs are not covered.
        schema:
          type: string
          pattern: ^\.?[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$
          maxLength: 64
          description: One covered ASCII top-level extension, such as com or .com. Multi-part suffixes and IDNs are not covered.
      - name: registrar
        in: query
        required: false
        description: Connected registrar ID from the registrars endpoint. Omit to compare all.
        schema:
          type: string
          maxLength: 40
          pattern: ^[a-z0-9-]+$
          description: Connected registrar ID from the registrars endpoint. Omit to compare all.
      - name: fresh
        in: query
        required: false
        description: 'Explicitly request a fresh single-name recheck only when the user asks. Normal checks reuse saved evidence: five minutes, or up to 30 days for a name found taken. Fresh checks still obey provider gates, pending claims, caller limits and cooldowns; never use in a loop.'
        schema:
          type: boolean
          default: false
          description: 'Explicitly request a fresh single-name recheck only when the user asks. Normal checks reuse saved evidence: five minutes, or up to 30 days for a name found taken. Fresh checks still obey provider gates, pending claims, caller limits and cooldowns; never use in a loop.'
      responses:
        '200':
          description: Success. Inspect coverage, stale flags, minimum terms and pagination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Availability'
        '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
components:
  schemas:
    Availability:
      type: object
      required:
      - domain
      - status
      - reason
      - message
      - provider
      - checkedAt
      - expiresAt
      - service
      - apiVersion
      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.'
        service:
          $ref: '#/components/schemas/ServiceInformation'
        apiVersion:
          type: string
    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
    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
externalDocs:
  description: Human and AI integration guide
  url: https://www.cheapest.domains/developers