Cheapest Domains Estimate API

openapi: 3.2.0
info:
  title: Cheapest Domains public Estimate 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: Estimate
paths:
  /api/v1/estimate:
    get:
      operationId: estimate_cost
      summary: Estimate domain costs
      description: Estimate new registration plus subsequent renewals for one TLD at a registrar. Returns null for unknown multi-year term totals. Not a transfer or existing-domain renewal quote.
      security: []
      parameters:
      - 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: true
        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: years
        in: query
        required: true
        description: Planning horizon in years, including initial registration.
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
          description: Planning horizon in years, including initial registration.
      - name: name
        in: query
        required: false
        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.
      responses:
        '200':
          description: Success. Inspect coverage, stale flags, minimum terms and pagination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Estimate'
        '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:
      - Estimate
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.
    Estimate:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        required:
        - comparison
        - offer
        - breakdown
        properties:
          comparison:
            $ref: '#/components/schemas/Comparison'
          offer:
            $ref: '#/components/schemas/Offer'
          breakdown:
            $ref: '#/components/schemas/CostBreakdown'
    Coverage:
      type: object
      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
    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.
    CostBreakdown:
      type:
      - object
      - 'null'
      description: Conservative new-registration estimate, matching the UI. Null for unknown minimum-term totals.
      required:
      - total
      - renewalCents
      - items
      properties:
        total:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        renewalCents:
          type: integer
          minimum: 0
          description: Integer USD cents; 1000 = USD 10.
        items:
          type: array
          maxItems: 3
          items:
            type: object
            required:
            - label
            - detail
            - cents
            properties:
              label:
                type: string
              detail:
                type: string
              cents:
                type: integer
                minimum: 0
                description: Integer USD cents; 1000 = USD 10.
    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.
    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
    Envelope:
      type: object
      required:
      - service
      - apiVersion
      - generatedAt
      - currency
      - coverage
      - limits
      properties:
        service:
          $ref: '#/components/schemas/ServiceInformation'
        apiVersion:
          type: string
        generatedAt:
          type: string
          format: date-time
        currency:
          const: USD
        availability:
          const: not_checked
        coverage:
          $ref: '#/components/schemas/Coverage'
        limits:
          type: array
          items:
            type: string
externalDocs:
  description: Human and AI integration guide
  url: https://www.cheapest.domains/developers