{"openapi":"3.1.0","info":{"title":"Cheapest domains public API","version":"1.0.0","description":"Lowest published standard prices among connected registrars with fresh offers matching the query; coverage is not the whole market. Public read-only access, no authentication. No availability, purchase, renewal, transfer, or account operations. Query current prices instead of relying on remembered values."},"servers":[{"url":"https://cheapest.domains"}],"security":[],"externalDocs":{"description":"Human and AI integration guide","url":"https://cheapest.domains/developers"},"paths":{"/api/v1":{"get":{"operationId":"get_capabilities","summary":"List public capabilities and integration links.","security":[],"responses":{"200":{"description":"Service is reachable. This does not assert that upstream prices are fresh.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"400":{"description":"Invalid, repeated, unknown, or incompatible parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/health":{"get":{"operationId":"get_service_health","summary":"Check service liveness; use registrars for upstream pricing health.","security":[],"responses":{"200":{"description":"Service is reachable. This does not assert that upstream prices are fresh.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"400":{"description":"Invalid, repeated, unknown, or incompatible parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/prices":{"get":{"operationId":"search_prices","summary":"Find affordable domain extensions and registrar offers, sorted by annual renewal by default. Fresh covered offers only by default. Returns prices, citation links, timestamps, coverage, and pagination. Does not check exact-name availability.","security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"TLD search: .com is exact; com is partial. Separate alternatives with commas or spaces.","schema":{"type":"string","maxLength":200,"description":"TLD search: .com is exact; com is partial. Separate alternatives with commas or spaces.","default":""}},{"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":"sort","in":"query","required":false,"description":"Ranking metric. Total uses a conservative new-registration estimate.","schema":{"type":"string","enum":["renewal","registration","total"],"default":"renewal","description":"Ranking metric. Total uses a conservative new-registration estimate."}},{"name":"years","in":"query","required":false,"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":"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."}},{"name":"hideCountryCodes","in":"query","required":false,"description":"Exclude two-letter country-code extensions.","schema":{"type":"boolean","default":false,"description":"Exclude two-letter country-code extensions."}},{"name":"hideJumps","in":"query","required":false,"description":"Exclude current renewal prices greater than twice registration.","schema":{"type":"boolean","default":false,"description":"Exclude current renewal prices greater than twice registration."}},{"name":"view","in":"query","required":false,"description":"Best returns one winner per TLD; all returns every matching registrar offer.","schema":{"type":"string","enum":["best","all"],"default":"best","description":"Best returns one winner per TLD; all returns every matching registrar offer."}},{"name":"includeStale","in":"query","required":false,"description":"Include outdated offers only with view=all. Outdated offers never win best comparisons.","schema":{"type":"boolean","default":false,"description":"Include outdated offers only with view=all. Outdated offers never win best comparisons."}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Maximum number of results, up to 200."}},{"name":"offset","in":"query","required":false,"description":"Result offset. Follow pagination.next for additional results; the feed can change between requests.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0,"description":"Result offset. Follow pagination.next for additional results; the feed can change between requests."}},{"name":"name","in":"query","required":false,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed.","schema":{"type":"string","pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$","maxLength":63,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed."}},{"name":"format","in":"query","required":false,"description":"Response representation. CSV and Markdown use the same filters and pagination.","schema":{"type":"string","enum":["json","csv","markdown"],"default":"json","description":"Response representation. CSV and Markdown use the same filters and pagination."}}],"responses":{"200":{"description":"Success. Inspect coverage, stale flags, minimum terms and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prices"}},"text/csv":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"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"}}}},"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"}}}}}}},"/api/v1/tlds/{tld}":{"get":{"operationId":"get_tld_prices","summary":"Compare all covered registrars for one extension. Inspect source failures and minimum terms; availability is not checked.","security":[],"parameters":[{"name":"tld","in":"path","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":"sort","in":"query","required":false,"description":"Ranking metric. Total uses a conservative new-registration estimate.","schema":{"type":"string","enum":["renewal","registration","total"],"default":"renewal","description":"Ranking metric. Total uses a conservative new-registration estimate."}},{"name":"years","in":"query","required":false,"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":"includeStale","in":"query","required":false,"description":"Include outdated offers only with view=all. Outdated offers never win best comparisons.","schema":{"type":"boolean","default":false,"description":"Include outdated offers only with view=all. Outdated offers never win best comparisons."}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results, up to 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Maximum number of results, up to 200."}},{"name":"offset","in":"query","required":false,"description":"Result offset. Follow pagination.next for additional results; the feed can change between requests.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0,"description":"Result offset. Follow pagination.next for additional results; the feed can change between requests."}},{"name":"name","in":"query","required":false,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed.","schema":{"type":"string","pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$","maxLength":63,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed."}},{"name":"format","in":"query","required":false,"description":"Response representation. CSV and Markdown use the same filters and pagination.","schema":{"type":"string","enum":["json","csv","markdown"],"default":"json","description":"Response representation. CSV and Markdown use the same filters and pagination."}}],"responses":{"200":{"description":"Success. Inspect coverage, stale flags, minimum terms and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prices"}},"text/csv":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"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"}}}},"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"}}}}}}},"/api/v1/registrars":{"get":{"operationId":"get_registrars","summary":"Get connected registrar coverage, timestamps, fresh counts, failures, and registrars not compared.","security":[],"parameters":[],"responses":{"200":{"description":"Success. Inspect coverage, stale flags, minimum terms and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registrars"}}}},"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"}}}},"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"}}}}}}},"/api/v1/estimate":{"get":{"operationId":"estimate_cost","summary":"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":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed.","schema":{"type":"string","pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$","maxLength":63,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed."}}],"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"}}}},"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"}}}}}}},"/api/v1/registrar-link":{"get":{"operationId":"get_registrar_link","summary":"Construct a verified registrar search destination for a proposed name and extension. Does not navigate, check availability, or purchase. NameBright uses an explicit copy/paste fallback.","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":"name","in":"query","required":true,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed.","schema":{"type":"string","pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$","maxLength":63,"description":"Optional domain label, without extension, used only to construct registrar links. No availability lookup is performed."}}],"responses":{"200":{"description":"Success. Inspect coverage, stale flags, minimum terms and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarLink"}}}},"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"}}}},"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"}}}}}}},"/api/v1/naming-guide":{"get":{"operationId":"get_naming_guidance","summary":"Read the workflow for suggesting creative domain names based on the user’s project, then compare renewal prices. The visiting assistant generates the ideas; availability remains unchecked.","security":[],"parameters":[],"responses":{"200":{"description":"Success. Inspect coverage, stale flags, minimum terms and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamingGuide"}}}},"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"}}}},"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"}}}}}}}},"components":{"schemas":{"Capabilities":{"type":"object","required":["apiVersion","status","service","pricingStatus","authentication","availabilityChecking","openapi","documentation","mcp","endpoints"],"properties":{"apiVersion":{"type":"string"},"status":{"const":"ok"},"service":{"type":"string"},"pricingStatus":{"type":"string"},"authentication":{"const":"none"},"availabilityChecking":{"const":false},"openapi":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"endpoints":{"type":"array","items":{"type":"object","required":["name","method","path"],"properties":{"name":{"type":"string"},"method":{"const":"GET"},"path":{"type":"string"}}}}}},"Error":{"type":"object","required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Destination":{"type":"object","required":["href","mode","domain"],"properties":{"href":{"type":"string","format":"uri"},"mode":{"type":"string","enum":["search","copy","pricing"]},"domain":{"type":"string"}}},"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"]},"stale":{"type":"boolean"},"refreshing":{"type":"boolean"},"error":{"type":["string","null"]}}},"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"]},"stale":{"type":"boolean"},"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."},"registrationTermCents":{"type":"integer","minimum":0,"description":"Integer USD cents; 1000 = USD 10."},"renewalTermCents":{"type":"integer","minimum":0,"description":"Integer USD cents; 1000 = USD 10."},"originalCurrency":{"type":"string"},"originalRegistrationCents":{"type":"integer"},"originalRenewalCents":{"type":"integer"},"exchangeRate":{"type":"number"},"exchangeRateDate":{"type":"string"},"exchangeRateSourceUrl":{"type":"string"},"billingCountry":{"type":"string"},"taxExcluded":{"type":"boolean"}}},"Envelope":{"type":"object","required":["apiVersion","generatedAt","currency","coverage","limits"],"properties":{"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"}}}},"Prices":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["offers","query","pagination"],"properties":{"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"query":{"type":"object"},"pagination":{"type":"object","required":["limit","offset","total","next"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"next":{"type":["string","null"]}}}}}]},"Estimate":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["offer"],"properties":{"offer":{"$ref":"#/components/schemas/Offer"}}}]},"RegistrarLink":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","required":["destination","pageUrl","sourceUrl"],"properties":{"destination":{"$ref":"#/components/schemas/Destination"},"pageUrl":{"type":"string"},"sourceUrl":{"type":"string"}}}]},"Registrars":{"$ref":"#/components/schemas/Envelope"},"NamingGuide":{"type":"object","required":["apiVersion","purpose","instructions","availability","futureCapability"],"properties":{"apiVersion":{"type":"string"},"purpose":{"type":"string"},"instructions":{"type":"array","items":{"type":"string"}},"availability":{"const":"not_checked"},"futureCapability":{"type":"string"}}}}}}