Cheapest Domains Name Comparison API

openapi: 3.2.0
info:
  title: Cheapest Domains public Name Comparison 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: Name Comparison
paths:
  /api/v1/name-comparison:
    get:
      operationId: compare_domain_names
      summary: Compare suggested domain names
      description: After checking exact names with the availability tools, compare up to 10 candidates using saved renewal-first prices and fresh cached evidence. No new availability requests; cache misses are Not confirmed. Returns standard reference offers, premium facts, dates and links. The assistant explains project fit. Split larger lists into bounded groups. Does not generate names.
      security: []
      parameters:
      - name: domains
        in: query
        required: true
        description: One to 10 distinct exact ASCII domains separated by commas or whitespace, such as brightkit.com,brightkit.dev. One label and one top-level extension per domain; no URLs, multi-part suffixes or IDNs.
        schema:
          type: string
          maxLength: 1279
          description: One to 10 distinct exact ASCII domains separated by commas or whitespace, such as brightkit.com,brightkit.dev. One label and one top-level extension per domain; no URLs, multi-part suffixes or IDNs.
      - name: maxRenewalCents
        in: query
        required: false
        description: Maximum annual renewal in integer USD cents; 1000 means USD 10.
        schema:
          type: integer
          minimum: 0
          maximum: 100000000
          description: Maximum annual renewal in integer USD cents; 1000 means USD 10.
      responses:
        '200':
          description: Success. Inspect coverage, stale flags, minimum terms and pagination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameComparison'
        '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:
      - Name Comparison
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
    Destination:
      type: object
      required:
      - href
      - mode
      - domain
      properties:
        href:
          type: string
          format: uri
        mode:
          type: string
          enum:
          - search
          - copy
          - pricing
        domain:
          type: string
    Comparison:
      type: object
      required:
      - url
      - omittedParameters
      description: Revisit current standard prices with supported website filters. Omits proposed names and API pagination; does not save prices or availability.
      properties:
        url:
          type: string
          format: uri
        omittedParameters:
          type: array
          items:
            enum:
            - years
            - favorites
          description: Estimate horizons outside 2, 3, 5 and 10 years use the website default. Favorites are browser-local preferences and are never written by a link. Disclose omitted settings.
    Offer:
      type: object
      required:
      - tld
      - registrarId
      - registrarName
      - currency
      - registrationCents
      - renewalCents
      - minimumTermYears
      - stale
      - estimatedTotalCents
      - estimateYears
      - availability
      - pageUrl
      - sourceUrl
      - registrarSearch
      properties:
        tld:
          type: string
        registrarId:
          type: string
        registrarName:
          type: string
        currency:
          const: USD
        registrationCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        renewalCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        minimumTermYears:
          type: integer
          minimum: 1
        countryCode:
          type: boolean
        sourceUrl:
          type: string
          format: uri
        fetchedAt:
          type:
          - string
          - 'null'
        nextRefreshAt:
          type:
          - string
          - 'null'
          description: When the saved catalog is due for its next scheduled refresh; not an expiry of its prices.
        stale:
          type: boolean
          description: True when the source’s last refresh failed and its saved catalog is at least 24 hours old. Passing nextRefreshAt alone does not make prices stale; a scheduled refresh every 15 minutes replaces due catalogs.
        estimatedTotalCents:
          type:
          - integer
          - 'null'
          description: Null for multi-year minimum terms; not zero.
        estimateYears:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
          description: Planning horizon in years, including initial registration.
        availability:
          const: not_checked
        pageUrl:
          type: string
          format: uri
        registrarSearch:
          $ref: '#/components/schemas/Destination'
        futureRenewalCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        futureRenewalDate:
          type: string
        regularRenewalCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        regularRegistrationCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        transferCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        registrationTermCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        renewalTermCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        pricingBasis:
          type: string
          enum:
          - sampled_standard
          - sampled_api
          description: 'Absent for published price lists. sampled_standard: standard-tier prices sampled from registrar search results (Cloudflare). sampled_api (API 1.9.0): registrar API purchase and auto-renewal rates sampled with a synthetic name (GoDaddy); the registrar website and manual renewals can charge more. Both have limited coverage and are not exact-name quotes. Preserve this distinction when displaying or reusing prices.'
        originalCurrency:
          type: string
        originalRegistrationCents:
          type: integer
        originalRenewalCents:
          type: integer
        exchangeRate:
          type: number
        exchangeRateDate:
          type: string
        exchangeRateSourceUrl:
          type: string
        billingCountry:
          type: string
        taxExcluded:
          type: boolean
        priceValidUntil:
          type: string
          format: date-time
          description: When a scheduled price change takes effect or the exchange rate behind a converted price expires; recheck after this time.
        renewalSince:
          type: string
          format: date-time
          description: 'API 1.12.0: when this renewal price (with its regular price) was first seen; unchanged since. Absent when not yet dated. See renewalSinceFirstRecord and the price history endpoint.'
        renewalSinceFirstRecord:
          type: boolean
          description: True when renewalSince is our earliest record of this price, so the price may be older. Say "unchanged since at least" that date.
    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.'
    Source:
      type: object
      required:
      - id
      - name
      - url
      - offerCount
      - freshOfferCount
      - stale
      - refreshing
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        note:
          type: string
        offerCount:
          type: integer
        freshOfferCount:
          type: integer
        fetchedAt:
          type:
          - string
          - 'null'
        nextRefreshAt:
          type:
          - string
          - 'null'
          description: When the saved catalog is due for its next scheduled refresh; not an expiry of its prices.
        stale:
          type: boolean
          description: True when the source’s last refresh failed and its saved catalog is at least 24 hours old. Passing nextRefreshAt alone does not make prices stale; a scheduled refresh every 15 minutes replaces due catalogs.
        refreshing:
          type: boolean
        error:
          type:
          - string
          - 'null'
        refresh:
          type: object
          required:
          - phase
          - completed
          - total
          - startedAt
          - resumeAt
          description: Progress of a staged catalog refresh, when one exists. Saved prices remain usable meanwhile.
          properties:
            phase:
              enum:
              - queued
              - running
              - waiting
              - paused
              - complete
            completed:
              type: integer
              minimum: 0
            total:
              type: integer
              minimum: 0
            startedAt:
              type: integer
              description: Unix time in milliseconds.
            resumeAt:
              type: integer
              description: Unix time in milliseconds.
    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.
    NameComparison:
      type: object
      required:
      - apiVersion
      - service
      - generatedAt
      - currency
      - cachedOnly
      - priceScope
      - rows
      - unconfirmedDomains
      - partial
      - limits
      properties:
        apiVersion:
          type: string
        service:
          $ref: '#/components/schemas/ServiceInformation'
        generatedAt:
          type: string
          format: date-time
        currency:
          const: USD
        cachedOnly:
          const: true
        priceScope:
          type: string
        partial:
          type: boolean
        limits:
          type: array
          items:
            type: string
        unconfirmedDomains:
          type: array
          maxItems: 10
          items:
            type: string
        rows:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: object
            required:
            - domain
            - name
            - tld
            - availability
            - offers
            - coverage
            - comparison
            properties:
              domain:
                type: string
              name:
                type: string
              tld:
                type: string
              availability:
                $ref: '#/components/schemas/AvailabilityEvidence'
              offers:
                type: array
                maxItems: 200
                items:
                  $ref: '#/components/schemas/Offer'
              comparison:
                $ref: '#/components/schemas/Comparison'
              coverage:
                type:
                - object
                - 'null'
                required:
                - scope
                - totalOffers
                - freshOffers
                - sources
                - notCompared
                - partial
                properties:
                  scope:
                    type: string
                  totalOffers:
                    type: integer
                  freshOffers:
                    type: integer
                  partial:
                    type: boolean
                  error:
                    type:
                    - string
                    - 'null'
                  sources:
                    type: array
                    items:
                      $ref: '#/components/schemas/Source'
                  notCompared:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        url:
                          type: string
                        reason:
                          type: string
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            retryAfterSeconds:
              type: number
              minimum: 0
    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