{"openapi":"3.1.0","info":{"title":"TLD Bench API","version":"008529282c4837ce6c52349f8c31939e91b60033","description":"Domain prices for every TLD at every registrar. Public and read-only; no API key. Prices are refreshed daily from each registrar's own price list; every price carries its source and when it was last confirmed. Money is {amount, currency} in major units, converted to ?currency= (default USD) with the rates disclosed in `fx`; unknown is null, never 0. The operationIds match the MCP server's tool names (https://tldbench.com/mcp). Manual: https://tldbench.com/llms.txt"},"servers":[{"url":"https://tldbench.com"}],"tags":[{"name":"tlds","description":"Extensions and their prices"},{"name":"registrars","description":"Registrars and their price lists"},{"name":"prices","description":"Cheapest, cost of ownership, changes, promotions"},{"name":"availability","description":"Is a name free, and what does it cost to own"},{"name":"meta","description":"Sources, freshness, counts"}],"paths":{"/v1/tlds":{"get":{"operationId":"list_tlds","summary":"Every extension with its cheapest prices","description":"One row per extension (com, co.uk, uk.com): type, how many registrars sell it, the cheapest register and renew price and N-year total, the median renewal, and popularity.","tags":["tlds"],"parameters":[{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"priced","in":"query","required":false,"description":"only extensions with a current price (default); false lists every known extension","schema":{"default":"true","type":"string","enum":["true","false"]}},{"name":"kind","in":"query","required":false,"description":"tld: a root label (com); registry_sld: a second level the TLD's registry runs (co.uk); private_sld: a second level a company sells under someone else's TLD (uk.com)","schema":{"type":"string","enum":["tld","registry_sld","private_sld"]}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"include_resellers","in":"query","required":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldList"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tlds/{tld}":{"get":{"operationId":"get_tld","summary":"One extension: facts and price summary","tags":["tlds"],"parameters":[{"name":"tld","in":"path","required":true,"description":"an extension, as an A-label or U-label, with or without the dot","schema":{"type":"string"},"example":"co.uk"},{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"include_resellers","in":"query","required":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldDetail"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tlds/{tld}/prices":{"get":{"operationId":"compare_tld_prices","summary":"Every registrar's prices for one extension, ranked by N-year total","tags":["tlds"],"parameters":[{"name":"tld","in":"path","required":true,"description":"an extension, as an A-label or U-label, with or without the dot","schema":{"type":"string"},"example":"co.uk"},{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"sort","in":"query","required":false,"schema":{"default":"total","type":"string","enum":["total","register","renew","transfer"]}},{"name":"include_stale","in":"query","required":false,"schema":{"default":"true","type":"string","enum":["true","false"]}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"include_resellers","in":"query","required":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldPrices"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tlds/{tld}/history":{"get":{"operationId":"price_history","summary":"How one extension's prices have changed","tags":["tlds"],"parameters":[{"name":"tld","in":"path","required":true,"description":"an extension, as an A-label or U-label, with or without the dot","schema":{"type":"string"},"example":"co.uk"},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"registrar","in":"query","required":false,"schema":{"type":"string"}},{"name":"operation","in":"query","required":false,"description":"register (a new registration, year 1), renew (one more year), transfer (move in; usually adds a year), restore (redeem an expired domain in its redemption period)","schema":{"type":"string","enum":["register","renew","transfer","restore"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldHistory"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/registrars":{"get":{"operationId":"list_registrars","summary":"Every registrar we track","tags":["registrars"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarList"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/registrars/{id}":{"get":{"operationId":"get_registrar","summary":"One registrar","tags":["registrars"],"parameters":[{"name":"id","in":"path","required":true,"description":"the registrar's id","schema":{"type":"string"},"example":"porkbun"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarDetail"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/registrars/{id}/prices":{"get":{"operationId":"get_registrar_prices","summary":"One registrar's full price list","tags":["registrars"],"parameters":[{"name":"id","in":"path","required":true,"description":"the registrar's id","schema":{"type":"string"},"example":"porkbun"},{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarPrices"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/registrars/{id}/icon":{"get":{"operationId":"get_registrar_icon","summary":"The registrar's icon (its apple-touch-icon or favicon)","tags":["registrars"],"parameters":[{"name":"id","in":"path","required":true,"description":"the registrar's id","schema":{"type":"string"},"example":"porkbun"}],"responses":{"200":{"description":"the image","content":{"image/*":{"schema":{"type":"string","contentEncoding":"binary"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cheapest":{"get":{"operationId":"cheapest_registrar","summary":"The cheapest registrar for each extension over N years","tags":["prices"],"parameters":[{"name":"tlds","in":"query","required":true,"description":"comma-separated extensions, at most 20","schema":{"type":"string"}},{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"operation","in":"query","required":false,"schema":{"default":"register","type":"string","enum":["register","transfer"]}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"include_resellers","in":"query","required":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cheapest"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cost":{"post":{"operationId":"total_cost_of_ownership","summary":"The cost of owning domains or extensions for N years","description":"Minimum terms and regular renewals applied (computeTco). With transfer_after_year, also the cheapest registrar to transfer to later and the saving.","tags":["prices"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"description":"1-20 domain names (their extensions are priced)","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}},"tlds":{"description":"1-20 extensions","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":253,"description":"an extension: com, .io, co.uk or рф","examples":["io"]}},"registrar":{"description":"price at this registrar; default: the cheapest to own","type":"string","minLength":1,"maxLength":100},"years":{"default":3,"description":"horizon for totals, 1-10 years (default 3)","type":"integer","minimum":1,"maximum":10},"transfer_after_year":{"description":"also price moving to the cheapest renewing registrar after this many years","type":"integer","minimum":1,"maximum":9},"currency":{"description":"ISO 4217 currency for prices (default USD); converted at the ECB's daily rate, disclosed in `fx`","type":"string","pattern":"^[A-Za-z]{3}$"},"include_limited_promos":{"default":false,"description":"count limited promotions (one per customer, first-time customers only) in totals and rankings; default false: they are listed and flagged promo_limited, but year 1 is priced at the regular price","type":"boolean"},"include_resellers":{"default":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cost"}}}},"400":{"description":"the body is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/coupons":{"get":{"operationId":"list_coupons","summary":"Coupon codes seen at the registrars' own sources, and running promotions","tags":["prices"],"parameters":[{"name":"registrar","in":"query","required":false,"schema":{"type":"string"}},{"name":"tld","in":"query","required":false,"schema":{"type":"string"}},{"name":"operation","in":"query","required":false,"schema":{"type":"string","enum":["register","renew","transfer"]}},{"name":"active_only","in":"query","required":false,"description":"false: also coupons that expired in the last 30 days","schema":{"default":"true","type":"string","enum":["true","false"]}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coupons"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/availability":{"post":{"operationId":"check_availability","summary":"Are these names free? Up to 50 per request","description":"Layered: syntax and policy, our cache, a DNS pre-check, the registry's RDAP (WHOIS for a few ccTLDs, single checks only). `unknown` means no registry answered: it is not available. Counts each name against the availability limit.","tags":["availability"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":253},"description":"1-50 full names (example.com, bücher.de)","examples":[["acmeforge.com","acmeforge.io"]]},"mode":{"default":"fast","description":"fast: a DNS delegation is accepted as proof of registration; precise: always ask the registry (status codes, expiry)","type":"string","enum":["fast","precise"]},"with_prices":{"default":true,"description":"add the cheapest registrar's price for names that are free","type":"boolean"},"years":{"default":3,"description":"horizon for totals, 1-10 years (default 3)","type":"integer","minimum":1,"maximum":10},"currency":{"description":"ISO 4217 currency for prices (default USD); converted at the ECB's daily rate, disclosed in `fx`","type":"string","pattern":"^[A-Za-z]{3}$"},"include_limited_promos":{"default":false,"description":"count limited promotions (one per customer, first-time customers only) in totals and rankings; default false: they are listed and flagged promo_limited, but year 1 is priced at the regular price","type":"boolean"},"include_resellers":{"default":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","type":"boolean"}},"required":["domains"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"the body is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/availability/{domain}":{"get":{"operationId":"check_domain","summary":"Is this one name free?","description":"The same as POST /v1/availability with one name; edge-cached for 60 s.","tags":["availability"],"parameters":[{"name":"domain","in":"path","required":true,"description":"a full name","schema":{"type":"string"},"example":"example.com"},{"name":"mode","in":"query","required":false,"description":"fast: a DNS delegation proves registration; precise: always ask the registry","schema":{"default":"fast","type":"string","enum":["fast","precise"]}},{"name":"with_prices","in":"query","required":false,"schema":{"default":"true","type":"string","enum":["true","false"]}},{"name":"years","in":"query","required":false,"description":"horizon for totals, 1-10","schema":{"default":3,"type":"integer","minimum":1,"maximum":10}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 currency to convert prices to","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"include_limited_promos","in":"query","required":false,"description":"count limited promotions (one per customer, first-time customers) in totals and rankings; default false: they are shown, but year 1 is priced at the regular price","schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"include_resellers","in":"query","required":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","schema":{"default":"false","type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"no such extension or registrar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/search":{"post":{"operationId":"search_name_across_tlds","summary":"One name across many extensions, free ones by cost to own","tags":["availability"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":63,"description":"the label, without an extension (acmeforge)","examples":["acmeforge"]},"tlds":{"description":"1-50 extensions; default: the preset","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":253,"description":"an extension: com, .io, co.uk or рф","examples":["io"]}},"preset":{"description":"popular (default), tech, cheap, or country:<cc> (country:de)","type":"string","maxLength":40},"max_renew_price":{"description":"leave out extensions whose cheapest renewal is above this (in `currency`)","type":"number","exclusiveMinimum":0},"years":{"default":3,"description":"horizon for totals, 1-10 years (default 3)","type":"integer","minimum":1,"maximum":10},"currency":{"description":"ISO 4217 currency for prices (default USD); converted at the ECB's daily rate, disclosed in `fx`","type":"string","pattern":"^[A-Za-z]{3}$"},"include_limited_promos":{"default":false,"description":"count limited promotions (one per customer, first-time customers only) in totals and rankings; default false: they are listed and flagged promo_limited, but year 1 is priced at the regular price","type":"boolean"},"include_resellers":{"default":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","type":"boolean"}},"required":["name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameSearch"}}}},"400":{"description":"the body is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suggest":{"post":{"operationId":"suggest_names","summary":"Check and price name ideas (yours, or simple variants of keywords)","tags":["availability"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidates":{"description":"your own ideas: labels (brewly) or full names (brewly.co); labels are tried with each of `tlds`","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":253}},"keywords":{"description":"words to build names from with simple rules (prefixes, suffixes, TLD hacks, pairs)","maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"tlds":{"description":"extensions to try (default com)","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":253,"description":"an extension: com, .io, co.uk or рф","examples":["io"]}},"max_length":{"description":"longest label","type":"integer","minimum":2,"maximum":63},"max_renew_price":{"type":"number","exclusiveMinimum":0},"limit":{"default":20,"description":"names to check (each counts against the availability limit; default 20)","type":"integer","minimum":1,"maximum":50},"years":{"default":3,"description":"horizon for totals, 1-10 years (default 3)","type":"integer","minimum":1,"maximum":10},"currency":{"description":"ISO 4217 currency for prices (default USD); converted at the ECB's daily rate, disclosed in `fx`","type":"string","pattern":"^[A-Za-z]{3}$"},"include_limited_promos":{"default":false,"description":"count limited promotions (one per customer, first-time customers only) in totals and rankings; default false: they are listed and flagged promo_limited, but year 1 is priced at the regular price","type":"boolean"},"include_resellers":{"default":false,"description":"include registrars whose prices are a reseller account's tier (pricing_tier reseller, e.g. eNom); default false","type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Suggestions"}}}},"400":{"description":"the body is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/changes":{"get":{"operationId":"list_changes","summary":"Price changes, newest first","tags":["prices"],"parameters":[{"name":"since","in":"query","required":false,"description":"ISO date or time; default 7 days ago","schema":{"type":"string"}},{"name":"tld","in":"query","required":false,"schema":{"type":"string"}},{"name":"registrar","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":200,"type":"integer","minimum":1,"maximum":1000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Changes"}}}},"400":{"description":"a query parameter is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sources":{"get":{"operationId":"list_sources","summary":"Where the prices come from, how fresh each source is, and what is held for confirmation","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sources"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"operationId":"get_stats","summary":"Counts: extensions, registrars, prices, changes","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/status":{"get":{"operationId":"get_status","summary":"TLDs tracked and the freshness of the IANA source","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"429":{"description":"rate limited: wait for Retry-After seconds","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/healthz":{"get":{"operationId":"health","summary":"Liveness","tags":["meta"],"responses":{"200":{"description":"The API is up"}}}}},"components":{"schemas":{"Operation":{"type":"string","enum":["register","renew","transfer","restore"],"description":"register (a new registration, year 1), renew (one more year), transfer (move in; usually adds a year), restore (redeem an expired domain in its redemption period)"},"Money":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]}},"required":["amount","currency"],"description":"An amount in major units (12.99), in `currency`."},"PricingTier":{"type":"string","enum":["retail","reseller"],"description":"retail: anyone can buy at these prices; reseller: the prices are a reseller account's tier (eNom's Silver), left out of consumer rankings unless include_resellers=true"},"RegistrarNote":{"type":"object","properties":{"text":{"type":"string","examples":["NameSilo's free discount program prices .com at $12.00 (retail $19.99)."]},"url":{"description":"where the note's facts come from","type":["string","null"]},"checked_on":{"anyOf":[{"type":"string","format":"date","examples":["2026-11-05"]},{"type":"null"}]}},"required":["text","url","checked_on"],"description":"A short, sourced note about the registrar's prices (not a price we rank by)."},"RegistrarRef":{"type":"object","properties":{"id":{"type":"string","examples":["porkbun"]},"name":{"type":"string","examples":["Porkbun"]},"url":{"description":"the registrar's website (a plain link, no affiliate code)","type":["string","null"]},"pricing_tier":{"$ref":"#/components/schemas/PricingTier"},"note":{"anyOf":[{"$ref":"#/components/schemas/RegistrarNote"},{"type":"null"}]}},"required":["id","name","url"]},"CouponHint":{"type":"object","properties":{"code":{"type":"string","examples":["AWESOMENESS"]},"price":{"description":"this price with the code (year 1, or the one operation it covers)","$ref":"#/components/schemas/Money"},"saving":{"$ref":"#/components/schemas/Money"},"first_year_only":{"type":["boolean","null"]},"new_customers_only":{"type":["boolean","null"]},"max_per_customer":{"anyOf":[{"type":"integer"},{"type":"null"}]},"ends_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"last_seen_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"the last time we saw the code at its source; codes are not tested at checkout"},"source_url":{"type":"string"}},"required":["code","price","saving","first_year_only","new_customers_only","max_per_customer","ends_at","last_seen_at","source_url"],"description":"The coupon code that lowers this price most, as the registrar's own source lists it. Seen at the source, not tested at checkout. Never part of `price`, the totals or any ranking."},"PriceQuote":{"type":"object","properties":{"price":{"description":"what one year costs now (per year, whatever the term): the promotional price while a promotion runs, else the regular price","$ref":"#/components/schemas/Money"},"regular":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"the regular (list) price per year; null when unknown (the source gives only a promotional or first-year price)"},"promo":{"type":"boolean","description":"price is a promotion (first year only, or until promo_ends_at)"},"promo_ends_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"promo_conditions":{"description":"the source's conditions for the promotion, as text","type":["string","null"]},"promo_limited":{"type":"boolean","description":"the promotion is limited: capped per customer or for first-time / new customers only. It is shown, but totals, rankings and cheapest use the regular price instead (include_limited_promos=true counts it)"},"promo_years":{"type":"integer","description":"the promotion covers the first N years of the term (default 1)"},"promo_inferred":{"type":"boolean","description":"the source marks no promotion, but this register price is below the renewal: we treat it as a first-year price whose regular price is unknown"},"term_years":{"type":"integer","description":"the shortest term this operation is sold for, in years (2 for a .ai registration, or a transfer that adds 2 years); price is per year, so the operation costs price x term_years"},"scheduled":{"anyOf":[{"type":"object","properties":{"regular":{"$ref":"#/components/schemas/Money"},"from":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]}},"required":["regular","from"]},{"type":"null"}],"description":"a change of the regular per-year price the source has announced, and when it takes effect"},"native":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"price in the registrar's own currency, when it was converted; null when it is already in that currency"},"coupon":{"description":"a coupon code that lowers this price, beside it (never in it); null when none is listed","anyOf":[{"$ref":"#/components/schemas/CouponHint"},{"type":"null"}]}},"required":["price","regular","promo","promo_ends_at","promo_conditions","native"]},"TotalsYear":{"type":"object","properties":{"year":{"type":"integer"},"amount":{"$ref":"#/components/schemas/Money"},"kind":{"type":"string","enum":["register","transfer","renew"]},"promo":{"type":"boolean"}},"required":["year","amount","kind","promo"]},"Totals":{"type":"object","properties":{"years":{"type":"integer","description":"the horizon asked for (?years=)"},"years_paid":{"type":"integer","description":"years paid for: at least min_years when starting with a registration"},"start":{"type":"string","enum":["register","transfer"]},"first_payment":{"description":"charged at checkout: year 1 (promotional price if one runs) plus the rest of the minimum term at the regular price; for a transfer, the transfer price x its term","$ref":"#/components/schemas/Money"},"total":{"description":"first payment plus every later year at the regular renew price (never a renewal promotion)","$ref":"#/components/schemas/Money"},"per_year":{"description":"total / years_paid","$ref":"#/components/schemas/Money"},"promo_applied":{"type":"boolean","description":"year 1 is a promotional price"},"limited_promo_skipped":{"type":"boolean","description":"a limited promotion runs (per customer, first-time customers) and was not counted: year 1 is the regular price"},"estimated":{"type":"boolean","description":"a year whose regular price is unknown was priced at the regular renewal: the total is an estimate"},"breakdown":{"description":"year by year (in /v1/cheapest)","type":"array","items":{"$ref":"#/components/schemas/TotalsYear"}}},"required":["years","years_paid","start","first_payment","total","per_year","promo_applied"],"description":"The cost of owning the domain for `years` years (packages/core computeTco)."},"SourceRef":{"type":"object","properties":{"id":{"type":"string","examples":["porkbun"]},"kind":{"type":"string","enum":["api","price_list","page","mirror"],"description":"api: the registrar's own price API; price_list: a file or JSON the registrar publishes; page: its price page; mirror: a third party's copy of the registrar's prices"},"url":{"type":"string","description":"where the price was read"}},"required":["id","kind","url"]},"Offer":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"tld":{"type":"string","description":"the extension","examples":["com","co.uk"]},"register":{"anyOf":[{"$ref":"#/components/schemas/PriceQuote"},{"type":"null"}]},"renew":{"anyOf":[{"$ref":"#/components/schemas/PriceQuote"},{"type":"null"}]},"transfer":{"anyOf":[{"$ref":"#/components/schemas/PriceQuote"},{"type":"null"}]},"restore":{"anyOf":[{"$ref":"#/components/schemas/PriceQuote"},{"type":"null"}]},"min_years":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"the shortest registration term (2 for .ai at most registrars)"},"max_years":{"anyOf":[{"type":"integer"},{"type":"null"}]},"includes":{"type":"object","properties":{"whois_privacy":{"type":["boolean","null"]},"icann_fee":{"type":["boolean","null"]}},"required":["whois_privacy","icann_fee"]},"vat_included":{"type":["boolean","null"]},"totals":{"anyOf":[{"$ref":"#/components/schemas/Totals"},{"type":"null"}],"description":"null when the register or renew price is unknown"},"observed_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"the last time the source confirmed this price"},"source":{"$ref":"#/components/schemas/SourceRef"},"stale":{"type":"boolean","description":"not confirmed for 3x the source's collection interval"}},"required":["registrar","tld","register","renew","transfer","restore","min_years","max_years","includes","vat_included","totals","observed_at","source","stale"],"description":"One registrar's prices for one extension."},"FxRate":{"type":"object","properties":{"rate":{"type":"number","description":"units of the response currency per unit of this currency"},"date":{"type":"string","format":"date","examples":["2026-11-05"]},"source":{"type":"string"}},"required":["rate","date","source"]},"Fx":{"anyOf":[{"type":"object","properties":{"date":{"type":"string","format":"date","examples":["2026-11-05"],"description":"the date of the primary rates (ECB reference rates)"},"source":{"type":"string","examples":["European Central Bank euro foreign exchange reference rates"]},"rates":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/FxRate"},"description":"every rate used in this response, by native currency"}},"required":["date","source","rates"]},{"type":"null"}],"description":"How converted prices were converted; null when nothing needed converting."},"ExtensionKind":{"type":"string","enum":["tld","registry_sld","private_sld"],"description":"tld: a root label (com); registry_sld: a second level the TLD's registry runs (co.uk); private_sld: a second level a company sells under someone else's TLD (uk.com)"},"CheapestPrice":{"type":"object","properties":{"price":{"$ref":"#/components/schemas/Money"},"registrar":{"$ref":"#/components/schemas/RegistrarRef"}},"required":["price","registrar"]},"CheapestTotal":{"type":"object","properties":{"years":{"type":"integer"},"total":{"$ref":"#/components/schemas/Money"},"registrar":{"$ref":"#/components/schemas/RegistrarRef"}},"required":["years","total","registrar"]},"TldSummary":{"type":"object","properties":{"tld":{"type":"string","examples":["com","co.uk","xn--p1ai"]},"unicode":{"type":"string","examples":["com","рф"]},"kind":{"$ref":"#/components/schemas/ExtensionKind"},"level":{"type":"integer"},"root":{"type":"string","description":"the root label (uk for co.uk)"},"type":{"anyOf":[{"type":"string","enum":["generic","country-code","infrastructure"]},{"type":"null"}],"description":"the root label's IANA category"},"brand":{"type":"boolean","description":"a brand TLD (ICANN Specification 13): not sold to the public"},"idn":{"type":"boolean"},"registrars":{"type":"integer","description":"registrars with a current price"},"cheapest_register":{"anyOf":[{"$ref":"#/components/schemas/CheapestPrice"},{"type":"null"}],"description":"the lowest year-1 price; a limited promotion counts at its regular price"},"cheapest_renew":{"anyOf":[{"$ref":"#/components/schemas/CheapestPrice"},{"type":"null"}]},"cheapest_total":{"anyOf":[{"$ref":"#/components/schemas/CheapestTotal"},{"type":"null"}],"description":"the lowest total over `years` (default 3)"},"median_register":{"description":"the typical year-1 price (median over fresh offers; a limited promotion counts at its regular price)","anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"median_renew":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"popularity":{"anyOf":[{"type":"object","properties":{"domains":{"type":"integer"},"month":{"type":"string","examples":["2026-07"]},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["domains","month","rank"]},{"type":"null"}],"description":"domains under management from ICANN's monthly registry report (gTLDs only)"}},"required":["tld","unicode","kind","level","root","type","brand","idn","registrars","cheapest_register","cheapest_renew","cheapest_total","median_renew","popularity"]},"TldList":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"years":{"type":"integer"},"count":{"type":"integer"},"tlds":{"type":"array","items":{"$ref":"#/components/schemas/TldSummary"}}},"required":["as_of","currency","fx","years","count","tlds"]},"WholesaleEvent":{"type":"object","properties":{"tld":{"type":"string"},"operation":{"$ref":"#/components/schemas/Operation"},"effective_from":{"type":"string","format":"date","examples":["2026-11-05"]},"from":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"the previous registry fee; null for the first one we know"},"to":{"$ref":"#/components/schemas/Money"},"source":{"type":"object","properties":{"kind":{"type":"string"},"url":{"type":["string","null"]}},"required":["kind","url"]},"note":{"type":["string","null"]}},"required":["tld","operation","effective_from","from","to","source","note"],"description":"A registry (wholesale) fee and when it takes effect, in the registry's currency."},"TldFacts":{"type":"object","properties":{"manager":{"description":"the TLD manager in IANA's root zone database","type":["string","null"]},"registry_operator":{"description":"the registry operator under ICANN contract (gTLDs)","type":["string","null"]},"delegated_on":{"anyOf":[{"type":"string","format":"date","examples":["2026-11-05"]},{"type":"null"}]},"contract_terminated":{"type":["boolean","null"]},"dnssec":{"description":"the TLD is signed (a DS record in the root zone)","type":["boolean","null"]},"whois_server":{"type":["string","null"]},"rdap_urls":{"type":"array","items":{"type":"string"}},"iana_url":{"type":"string"},"third_level_registration":{"type":["boolean","null"]},"in_root":{"type":"boolean","description":"in IANA's root zone list today"},"psl_section":{"anyOf":[{"type":"string","enum":["icann","private"]},{"type":"null"}],"description":"where the Public Suffix List has this extension"}},"required":["manager","registry_operator","delegated_on","contract_terminated","dnssec","whois_server","rdap_urls","iana_url","third_level_registration","in_root","psl_section"]},"TldDetail":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"years":{"type":"integer"},"tld":{"$ref":"#/components/schemas/TldSummary"},"facts":{"$ref":"#/components/schemas/TldFacts"},"second_levels":{"type":"array","items":{"type":"string"},"description":"priced extensions under this root (co.uk, org.uk under uk)"},"wholesale":{"type":"array","items":{"$ref":"#/components/schemas/WholesaleEvent"},"description":"known registry fees, newest first"}},"required":["as_of","currency","fx","years","tld","facts","second_levels","wholesale"]},"TldPrices":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"tld":{"type":"string"},"years":{"type":"integer"},"sort":{"type":"string","enum":["total","register","renew","transfer"]},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"stats":{"type":"object","properties":{"registrars":{"type":"integer"},"min_register":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"a limited promotion counts at its regular price"},"median_register":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"median_renew":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"max_renew":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]}},"required":["registrars","min_register","median_renew","max_renew"]}},"required":["as_of","currency","fx","tld","years","sort","offers","stats"]},"HistoryPoint":{"type":"object","properties":{"from":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"to":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}],"description":"null while it is the current price"},"price":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"converted at the rate of `from`; null while not offered"},"native":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]}},"required":["from","to","price","native"]},"HistorySeries":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"operation":{"$ref":"#/components/schemas/Operation"},"kind":{"type":"string","enum":["regular","promo"]},"points":{"type":"array","items":{"$ref":"#/components/schemas/HistoryPoint"}}},"required":["registrar","operation","kind","points"]},"TldHistory":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"tld":{"type":"string"},"series":{"type":"array","items":{"$ref":"#/components/schemas/HistorySeries"}},"registry_events":{"type":"array","items":{"$ref":"#/components/schemas/WholesaleEvent"}}},"required":["as_of","currency","fx","tld","series","registry_events"],"description":"Price changes only: each point is a period during which the native price did not change. A currency move is never a change."},"RegistrarSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":["string","null"]},"country":{"description":"ISO 3166-1 alpha-2","type":["string","null"]},"kind":{"type":"string","enum":["retail","wholesale","cloud","registry-direct"]},"pricing_tier":{"$ref":"#/components/schemas/PricingTier"},"note":{"anyOf":[{"$ref":"#/components/schemas/RegistrarNote"},{"type":"null"}]},"family":{"description":"the group it belongs to (several brands, one owner)","type":["string","null"]},"iana_ids":{"type":"array","items":{"type":"integer"}},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"by gTLD domains under management (ICANN monthly registry reports), registrar groups counted together"},"domains":{"anyOf":[{"type":"integer"},{"type":"null"}]},"domains_month":{"type":["string","null"]},"extensions":{"type":"integer","description":"extensions with a current price"},"icon_url":{"type":["string","null"]},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"stale":{"type":"boolean"}},"required":["id","last_success_at","stale"]}}},"required":["id","name","url","country","kind","family","iana_ids","rank","domains","domains_month","extensions","icon_url","sources"]},"RegistrarList":{"type":"object","properties":{"count":{"type":"integer"},"registrars":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarSummary"}}},"required":["count","registrars"]},"RegistrarDetail":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarSummary"}},"required":["registrar"]},"RegistrarPrices":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"years":{"type":"integer"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}},"required":["as_of","currency","fx","registrar","years","offers"]},"CheapestResult":{"type":"object","properties":{"tld":{"type":"string"},"best":{"anyOf":[{"$ref":"#/components/schemas/Offer"},{"type":"null"}],"description":"the lowest total; its totals carry the year-by-year breakdown"},"runners_up":{"type":"array","items":{"$ref":"#/components/schemas/Offer"},"description":"the next three"},"caveats":{"type":"array","items":{"type":"string"},"description":"for example a minimum term or a first-year promotion"}},"required":["tld","best","runners_up","caveats"]},"Cheapest":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"years":{"type":"integer"},"operation":{"type":"string","enum":["register","transfer"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/CheapestResult"}}},"required":["as_of","currency","fx","years","operation","results"]},"PriceChange":{"type":"object","properties":{"at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"tld":{"type":"string"},"operation":{"$ref":"#/components/schemas/Operation"},"kind":{"type":"string","enum":["regular","promo"]},"change":{"type":"string","enum":["new","increase","decrease","withdrawn","returned","currency"],"description":"currency: the registrar now charges in another currency"},"from":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"native"},"to":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"native"},"pct":{"description":"percent change of the native amount","type":["number","null"]}},"required":["at","registrar","tld","operation","kind","change","from","to","pct"]},"Changes":{"type":"object","properties":{"since":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"count":{"type":"integer"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/PriceChange"},"description":"newest first; the first collection of a source is not a change"},"registry_events":{"type":"array","items":{"$ref":"#/components/schemas/WholesaleEvent"}}},"required":["since","count","changes","registry_events"]},"Hold":{"type":"object","properties":{"kind":{"type":"string","enum":["price_jump","coverage_drop"]},"tld":{"type":["string","null"]},"operation":{"anyOf":[{"$ref":"#/components/schemas/Operation"},{"type":"null"}]},"since":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"summary":{"type":"string"}},"required":["kind","tld","operation","since","summary"],"description":"A change not published until the next collection confirms it, or a short list kept from withdrawing prices."},"SourceStatus":{"type":"object","properties":{"id":{"type":"string"},"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"kind":{"type":"string","enum":["api","price_list","page","mirror"],"description":"api: the registrar's own price API; price_list: a file or JSON the registrar publishes; page: its price page; mirror: a third party's copy of the registrar's prices"},"url":{"type":"string"},"cadence_hours":{"type":"number"},"stale_after_hours":{"type":"number"},"last_run":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["running","succeeded","failed","abandoned"]},"started_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"finished_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"rows":{"anyOf":[{"type":"integer"},{"type":"null"}]},"rejected":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error":{"type":["string","null"]}},"required":["id","status","started_at","finished_at","rows","rejected","error"]},{"type":"null"}]},"last_success_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"stale":{"type":"boolean"},"prices":{"type":"integer","description":"current prices (extension x operation)"},"extensions":{"type":"integer"},"holds":{"type":"array","items":{"$ref":"#/components/schemas/Hold"}}},"required":["id","registrar","kind","url","cadence_hours","stale_after_hours","last_run","last_success_at","stale","prices","extensions","holds"]},"Sources":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceStatus"}}},"required":["generated_at","sources"]},"Stats":{"type":"object","properties":{"as_of":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"tlds":{"type":"object","properties":{"in_root":{"type":"integer"},"priced":{"type":"integer","description":"root labels with a current price"}},"required":["in_root","priced"]},"extensions":{"type":"object","properties":{"known":{"type":"integer"},"priced":{"type":"integer"}},"required":["known","priced"]},"registrars":{"type":"integer","description":"registrars with a current price"},"sources":{"type":"object","properties":{"total":{"type":"integer"},"stale":{"type":"integer"}},"required":["total","stale"]},"prices":{"type":"integer"},"changes_7d":{"type":"integer"},"fx_date":{"anyOf":[{"type":"string","format":"date","examples":["2026-11-05"]},{"type":"null"}]}},"required":["as_of","tlds","extensions","registrars","sources","prices","changes_7d","fx_date"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["not_found","bad_request"]},"message":{"type":"string"},"hint":{"type":["string","null"]}},"required":["code","message","hint"]}},"required":["error"]},"AvailabilityOffer":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"years":{"type":"integer"},"register":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"year 1 now (a promotion when one runs)"},"renew":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"the regular renewal"},"first_payment":{"$ref":"#/components/schemas/Money"},"total":{"description":"the cost to own it for `years` (computeTco), the same number as /v1/tlds/{tld}/prices","$ref":"#/components/schemas/Money"},"min_years":{"anyOf":[{"type":"integer"},{"type":"null"}]},"promo_first_year":{"type":"boolean"},"estimated":{"type":"boolean","description":"the total prices a year at the regular renewal because its own regular price is unknown"},"observed_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"source":{"$ref":"#/components/schemas/SourceRef"}},"required":["registrar","years","register","renew","first_payment","total","min_years","promo_first_year","observed_at","source"],"description":"The cheapest registrar to own the name for `years` (standard price; a premium name costs more)."},"AvailabilityResult":{"type":"object","properties":{"domain":{"type":"string","description":"the name as asked"},"ascii":{"description":"the A-label (punycode) form, the canonical spelling","examples":["xn--bcher-kva.de"],"type":["string","null"]},"unicode":{"type":["string","null"]},"tld":{"description":"the extension it is registered under (co.uk for example.co.uk)","type":["string","null"]},"status":{"type":"string","enum":["available","registered","pending_delete","redemption","unsupported","invalid","unknown"],"description":"available: the registry has no such name; registered; pending_delete / redemption: registered, in the deletion cycle; unsupported: not sold to the public (a brand TLD, not in the root, no registry lookup possible); invalid: not a domain name; unknown: no registry answered (NOT available)"},"registrable":{"description":"true when it can be registered at a standard price as far as we can tell; null when we can't tell (unknown, or premium_unknown)","type":["boolean","null"]},"premium_unknown":{"type":"boolean","description":"the registry's lookup can't tell a premium or reserved name from a free one (RDAP 404 on .ai, .io, new gTLDs with premium tiers): check the price at a registrar before promising it"},"confidence":{"type":"string","enum":["registry","dns","none"],"description":"registry: RDAP or WHOIS answered; dns: a DNS delegation proves it is registered; none: unknown"},"source":{"type":"string","enum":["rdap","whois","dns","policy","none"]},"cached":{"type":"boolean","description":"answered from our cache (available: 10 min, registered: 24 h, 1 h near expiry; unknown is never cached)"},"checked_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"cache_age_s":{"anyOf":[{"type":"integer"},{"type":"null"}]},"registry_status":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"RDAP status codes, e.g. [\"client transfer prohibited\"]"},"expires_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}],"description":"registration expiry from RDAP, when registered"},"reason":{"description":"why the status is unknown, unsupported or invalid; or a caveat","type":["string","null"]},"cheapest":{"anyOf":[{"$ref":"#/components/schemas/AvailabilityOffer"},{"type":"null"}],"description":"with_prices: the cheapest registrar for the extension, when the name is available or unknown"},"url":{"description":"the extension's page on tldbench.com","type":["string","null"]}},"required":["domain","ascii","unicode","tld","status","registrable","premium_unknown","confidence","source","cached","checked_at","cache_age_s","registry_status","expires_at","reason","cheapest","url"]},"Availability":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when this answer was put together"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"years":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilityResult"},"description":"in the order asked"},"notes":{"type":"array","items":{"type":"string"}}},"required":["as_of","currency","years","results","notes"]},"NameSearch":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"years":{"type":"integer"},"name":{"type":"string","description":"the label checked"},"tlds":{"type":"array","items":{"type":"string"}},"results":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilityResult"},"description":"available first, cheapest to own first; then unknown; then taken and the rest"},"notes":{"type":"array","items":{"type":"string"}}},"required":["as_of","currency","years","name","tlds","results","notes"]},"Suggestion":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["available","unknown"]},"premium_unknown":{"type":"boolean"},"confidence":{"type":"string","enum":["registry","dns","none"]},"cheapest":{"anyOf":[{"$ref":"#/components/schemas/AvailabilityOffer"},{"type":"null"}]},"why":{"type":"string","description":"how it was made: your candidate, or the rule (prefix, suffix, TLD hack, combination)"},"url":{"type":["string","null"]}},"required":["domain","status","premium_unknown","confidence","cheapest","why","url"]},"Suggestions":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"years":{"type":"integer"},"generated":{"type":"integer","description":"names made from the input before checking"},"checked":{"type":"integer"},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/Suggestion"},"description":"only names that are available or unknown: available first, cheapest first"},"notes":{"type":"array","items":{"type":"string"}}},"required":["as_of","currency","years","generated","checked","suggestions","notes"]},"CostSwitch":{"type":"object","properties":{"after_year":{"type":"integer"},"to":{"$ref":"#/components/schemas/RegistrarRef"},"transfer":{"$ref":"#/components/schemas/Money"},"total":{"description":"register at `registrar`, transfer to `to` after `after_year` years, renew there","$ref":"#/components/schemas/Money"},"saving":{"description":"total without the switch minus total with it","$ref":"#/components/schemas/Money"}},"required":["after_year","to","transfer","total","saving"]},"CostRow":{"type":"object","properties":{"input":{"type":"string","description":"the domain or extension as asked"},"domain":{"type":["string","null"]},"tld":{"type":["string","null"]},"registrar":{"anyOf":[{"$ref":"#/components/schemas/RegistrarRef"},{"type":"null"}],"description":"the registrar asked for, else the cheapest to own"},"totals":{"anyOf":[{"$ref":"#/components/schemas/Totals"},{"type":"null"}],"description":"with the year-by-year breakdown; null when no registrar has both prices"},"min_years":{"anyOf":[{"type":"integer"},{"type":"null"}]},"observed_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"source":{"anyOf":[{"$ref":"#/components/schemas/SourceRef"},{"type":"null"}]},"stale":{"type":["boolean","null"]},"switch":{"anyOf":[{"$ref":"#/components/schemas/CostSwitch"},{"type":"null"}],"description":"transfer_after_year: the cheapest registrar to transfer to, when that saves money"},"reason":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["input","domain","tld","registrar","totals","min_years","observed_at","source","stale","switch","reason","url"]},"Cost":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"when the newest price in this response was collected"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"years":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/CostRow"}}},"required":["as_of","currency","fx","years","rows"]},"Promotion":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"tld":{"type":"string"},"operation":{"$ref":"#/components/schemas/Operation"},"price":{"$ref":"#/components/schemas/Money"},"regular":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"promo_ends_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"promo_conditions":{"type":["string","null"]},"promo_limited":{"type":"boolean","description":"capped per customer or for first-time customers only"},"observed_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"source":{"$ref":"#/components/schemas/SourceRef"},"url":{"type":"string"}},"required":["registrar","tld","operation","price","regular","promo_ends_at","promo_conditions","observed_at","source","url"],"description":"A promotional price anyone gets now (no code needed), as the registrar lists it."},"Coupon":{"type":"object","properties":{"registrar":{"$ref":"#/components/schemas/RegistrarRef"},"code":{"type":"string","examples":["AWESOMENESS"]},"operation":{"$ref":"#/components/schemas/Operation"},"tlds":{"type":"array","items":{"type":"string"},"description":"the extensions the code applies to; empty when all_tlds"},"all_tlds":{"type":"boolean","description":"the source says the code applies to every extension"},"description":{"type":"string","examples":["1.00 USD off a registration, first year only, 1 per customer"]},"discount":{"type":"object","properties":{"kind":{"type":"string","enum":["amount","percent","price"],"description":"amount: `amount` off; percent: `percent`% off; price: the price with the code is `amount`"},"percent":{"type":["number","null"]},"amount":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"native":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"`amount` as the source gives it, when it was converted"}},"required":["kind","percent","amount","native"]},"first_year_only":{"type":["boolean","null"]},"new_customers_only":{"type":["boolean","null"]},"max_per_customer":{"anyOf":[{"type":"integer"},{"type":"null"}]},"starts_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"ends_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}],"description":"same as ends_at"},"terms":{"description":"the source's terms, as text","type":["string","null"]},"status":{"type":"string","enum":["active","expired"]},"expired_at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},{"type":"null"}]},"expired_reason":{"anyOf":[{"type":"string","enum":["ended","missing"]},{"type":"null"}],"description":"ended: past its end date; missing: its source stopped listing it (2 consecutive collections)"},"first_seen_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"last_seen_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"the last collection that saw the code at its source"},"observed_at":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"],"description":"same as last_seen_at"},"stale":{"type":"boolean","description":"its source hasn't been collected for 3x its interval"},"example":{"anyOf":[{"type":"object","properties":{"tld":{"type":"string"},"price":{"$ref":"#/components/schemas/Money"},"with_code":{"$ref":"#/components/schemas/Money"}},"required":["tld","price","with_code"]},{"type":"null"}],"description":"one extension's current price and the price with the code"},"source":{"$ref":"#/components/schemas/SourceRef"},"source_url":{"type":"string"}},"required":["registrar","code","operation","tlds","all_tlds","description","discount","first_year_only","new_customers_only","max_per_customer","starts_at","ends_at","expires_at","terms","status","expired_at","expired_reason","first_seen_at","last_seen_at","observed_at","stale","example","source","source_url"],"description":"A coupon code as the registrar's own API, price list or promotions page shows it. Seen at the source, never tested at checkout."},"Coupons":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time","examples":["2026-11-06T04:12:00.000Z"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217","examples":["USD"]},"fx":{"$ref":"#/components/schemas/Fx"},"coupons":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"},"description":"coupon codes seen at the registrars' own sources, by registrar"},"promotions":{"type":"array","items":{"$ref":"#/components/schemas/Promotion"},"description":"running promotional prices, cheapest first"},"note":{"type":"string"}},"required":["as_of","currency","fx","coupons","promotions","note"]},"Status":{"type":"object","properties":{"tlds":{"type":"object","properties":{"active":{"type":"integer"},"removed":{"type":"integer"},"idn":{"type":"integer"},"withRdap":{"type":"integer"}},"required":["active","removed","idn","withRdap"]},"sources":{"type":"object","properties":{"iana":{"anyOf":[{"type":"object","properties":{"lastSuccessAt":{"type":"string"},"stale":{"type":"boolean"},"ianaVersion":{"type":["string","null"]},"rdapPublication":{"type":["string","null"]},"urls":{"type":"array","items":{"type":"string"}}},"required":["lastSuccessAt","stale","ianaVersion","rdapPublication","urls"]},{"type":"null"}]}},"required":["iana"]},"generatedAt":{"type":"string"}},"required":["tlds","sources","generatedAt"]}}}}