{"openapi":"3.1.0","info":{"title":"DomainToolBelt API","version":"1.0.0","summary":"Domain sales, auctions, expiring domains, value estimates and trends.","description":"Read domain market data from DomainToolBelt: reported sales, live auctions, domains heading to deletion, last known status, stored value estimates and trending keywords.\n\nEvery answer carries a link to the matching domaintoolbelt.com page and an as_of time.\n\nSend your key as `Authorization: Bearer dtb_live_...`. Get one at https://domaintoolbelt.com/dashboard (API tab).\n\nNames you look up are never stored or shown anywhere.","contact":{"name":"DomainToolBelt","url":"https://domaintoolbelt.com/contact"},"termsOfService":"https://domaintoolbelt.com/terms"},"externalDocs":{"description":"Developer docs","url":"https://domaintoolbelt.com/apis"},"servers":[{"url":"https://domaintoolbelt.com/v1","description":"API host"},{"url":"https://domaintoolbelt.com/v1","description":"Same routes on the main site"}],"security":[{"bearerKey":[]}],"tags":[{"name":"Domains","description":"One name: status, summary, history, value."},{"name":"Market","description":"Lists: sales, auctions, expiring domains."},{"name":"Trends","description":"Keywords rising in new registrations."},{"name":"Names","description":"One word across domain endings."},{"name":"Availability","description":"Bulk availability checks."},{"name":"Account","description":"Your usage, your alerts and your alert webhook."}],"paths":{"/domains/{domain}":{"get":{"operationId":"getDomainStatus","summary":"Domain status","description":"Last known status of one domain: available, registered, or registered and for sale with the asking price. From our records, not a live check. Live checks for paid callers are coming soon.\n\nUnits: 1 query. Needs a paid plan or topped-up credits. MCP tool: get_domain_status.","tags":["Domains"],"x-dtb-status":"live","x-dtb-units":"1 query","x-dtb-free":false,"x-dtb-mcp-tool":"get_domain_status","parameters":[{"name":"domain","in":"path","required":true,"description":"Full domain name, e.g. coffee.ai.","schema":{"type":"string","example":"coffee.ai"}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainStatus"}}}]},"example":{"data":{"domain":"coffee.ai","status":"registered, for sale","for_sale":{"marketplace":"afternic","price":25000,"currency":"USD"},"url":"https://domaintoolbelt.com/domain/coffee.ai","note":"Last known status from our records, not a live check. Open the link for a live check before buying."},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/domain/coffee.ai"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"We hold nothing for this name or path."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/domains/{domain}/summary":{"get":{"operationId":"getDomainSummary","summary":"Domain summary","description":"Headline facts for one domain: status, for sale or in auction, last confirmed sale, value range and registration year. How many endings the name is taken in is its own endpoint, GET /emd/{name}. With a paid plan or topped-up credits the answer adds the sale count and the price and year of every sale.\n\nUnits: 1 query. Needs a paid plan or topped-up credits. MCP tool: get_domain_summary.","tags":["Domains"],"x-dtb-status":"live","x-dtb-units":"1 query","x-dtb-free":false,"x-dtb-mcp-tool":"get_domain_summary","parameters":[{"name":"domain","in":"path","required":true,"description":"Full domain name, e.g. coffee.ai.","schema":{"type":"string","example":"coffee.ai"}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainSummary"}}}]},"example":{"data":{"domain":"voice.com","status":"registered","for_sale":null,"in_auction":null,"last_sale":{"price":30000000,"currency":"USD","date":"2019-06","venue":null},"estimate":{"value":4200000,"low":2500000,"high":7000000,"currency":"USD"},"registered_since":1995,"url":"https://domaintoolbelt.com/domain/voice.com"},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/domain/voice.com"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"We hold nothing for this name or path."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/domains/{domain}/history":{"get":{"operationId":"getDomainHistory","summary":"Domain history timeline","description":"Every sale of one domain (price, date, venue) and its dated events, newest first: registered, registered again, dropped, pending delete, listed, no longer listed, asking price changed, moved marketplace, auction started, auction ended, auction ended without a sale, registrar changed. Paid keys only.\n\nUnits: 1 query. Needs a paid plan or topped-up credits. MCP tool: get_domain_timeline.","tags":["Domains"],"x-dtb-status":"live","x-dtb-units":"1 query","x-dtb-free":false,"x-dtb-mcp-tool":"get_domain_timeline","parameters":[{"name":"domain","in":"path","required":true,"description":"Full domain name, e.g. coffee.ai.","schema":{"type":"string","example":"coffee.ai"}},{"name":"limit","in":"query","description":"History events to return (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DomainTimeline"}}}]},"example":{"data":{"domain":"voice.com","sales_count":1,"sales":[{"price":30000000,"currency":"USD","date":"2019-06","venue":null,"reported":false}],"events":[{"event":"listed for sale","date":"2018-03-02","marketplace":"Afternic","price":35000000}],"url":"https://domaintoolbelt.com/domain/voice.com"},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/domain/voice.com"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"We hold nothing for this name or path."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/sales":{"get":{"operationId":"listSales","summary":"Search domain sales","description":"Reported domain sales with price, date and venue. A free key gets the top 3 rows with the total count; a paid plan or topped-up credits get full pages and the full archive.\n\nUnits: 1 query per page. Needs a paid plan or topped-up credits. MCP tool: search_domain_sales.","tags":["Market"],"x-dtb-status":"live","x-dtb-units":"1 query per page","x-dtb-free":false,"x-dtb-mcp-tool":"search_domain_sales","parameters":[{"name":"query","in":"query","description":"Keyword to match inside the domain name, e.g. \"coffee\".","schema":{"type":"string"}},{"name":"tld","in":"query","description":"Domain ending without the dot, e.g. \"com\", \"ai\", \"io\".","schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Lowest sale price in USD.","schema":{"type":"integer","minimum":0}},{"name":"window","in":"query","description":"Time window. Defaults to the last 7 days when no query is given, and to all time when one is.","schema":{"type":"string","enum":["24h","7d","30d","all"]}},{"name":"sort","in":"query","description":"Order: newest first, or highest price first.","schema":{"type":"string","enum":["date","price"],"default":"date"}},{"name":"limit","in":"query","description":"Rows to return. Free answers hold 3 rows; a paid key gets up to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","description":"Page number, paid keys only (free answers are page 1).","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sale"}}}}]},"example":{"data":[{"domain":"brew.ai","price":42000,"currency":"USD","sale_date":"2026-10-28","venue":"Afternic","reported":true,"url":"https://domaintoolbelt.com/domain/brew.ai"}],"page":1,"limit":25,"total":1284,"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/sales"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/auctions":{"get":{"operationId":"listAuctions","summary":"Search live auctions","description":"Live expired-domain and aftermarket auctions: current bid, bid count, end time and our estimate. Covers the 20 public endings.\n\nUnits: 1 per page. Works with a free key. MCP tool: search_auctions.","tags":["Market"],"x-dtb-status":"live","x-dtb-units":"1 per page","x-dtb-free":true,"x-dtb-mcp-tool":"search_auctions","parameters":[{"name":"query","in":"query","description":"Keyword to match inside the domain name, e.g. \"coffee\".","schema":{"type":"string"}},{"name":"tld","in":"query","description":"Domain ending without the dot, e.g. \"com\", \"ai\", \"io\".","schema":{"type":"string"}},{"name":"marketplace","in":"query","description":"Marketplace id, e.g. \"godaddy\", \"namejet\", \"dynadot\", \"dropcatch\".","schema":{"type":"string"}},{"name":"min_price","in":"query","description":"Lowest current bid in USD.","schema":{"type":"integer","minimum":0}},{"name":"max_price","in":"query","description":"Highest current bid in USD.","schema":{"type":"integer","minimum":0}},{"name":"ending_soon","in":"query","description":"Only auctions ending in the next 30 minutes.","schema":{"type":"boolean"}},{"name":"has_bids","in":"query","description":"Only auctions with at least one bid.","schema":{"type":"boolean"}},{"name":"query_mode","in":"query","description":"Where query sits in the name.","schema":{"type":"string","enum":["contains","starts_with","ends_with"],"default":"contains"}},{"name":"pattern","in":"query","description":"Name shape, one letter per character: L letter, N digit, C consonant, V vowel (a e i o u). E.g. \"LLL\", \"NNN\", \"LLN\", \"NNL\", \"CVC\", \"CVCV\". Sets the length.","schema":{"type":"string"}},{"name":"mask","in":"query","description":"Fixed characters by position: a-z, 0-9 and - are themselves, ? is any character, and capital L N C V are the classes of pattern. E.g. \"z??\" (3 characters starting with z), \"?a??\", \"ai??\", \"CVCo\". Sets the length and wins over pattern.","schema":{"type":"string"}},{"name":"name_type","in":"query","description":"dictionary = one dictionary word, two_words = two words, brandable = made-up but easy to say (5-8 letters), word_twist = one letter off a word (kube), prefix_word = prefix + word (getcoffee), word_suffix = word + suffix (coffeely).","schema":{"type":"string","enum":["dictionary","two_words","brandable","word_twist","prefix_word","word_suffix"]}},{"name":"min_length","in":"query","description":"Shortest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"max_length","in":"query","description":"Longest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"no_hyphens","in":"query","description":"Leave out names with a hyphen.","schema":{"type":"boolean"}},{"name":"no_numbers","in":"query","description":"Leave out names with a digit.","schema":{"type":"boolean"}},{"name":"min_age","in":"query","description":"Only names first registered at least this many years ago.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"max_age","in":"query","description":"Only names first registered at most this many years ago.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"sort","in":"query","description":"Order: ending soonest, highest bid, most bids, most endings taken (emd), highest domain rating (dr), oldest name first (age), or newest name first (age_newest).","schema":{"type":"string","enum":["ending","price","bids","emd","dr","age","age_newest"],"default":"ending"}},{"name":"limit","in":"query","description":"Rows to return. Free answers hold 3 rows; a paid key gets up to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","description":"Page number, paid keys only (free answers are page 1).","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Auction"}}}}]},"example":{"data":[{"domain":"lumo.com","marketplace":"godaddy","current_bid":1850,"currency":"USD","bids":23,"ends_at":"2026-10-30T18:05:00Z","type":"expired","our_estimate":{"value":4100,"low":2200,"high":7600},"url":"https://domaintoolbelt.com/domain/lumo.com"}],"page":1,"limit":25,"total":1284,"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/auctions"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/drops":{"get":{"operationId":"listDrops","summary":"List expiring domains","description":"Registered domains that expired and are heading toward deletion. A free key gets the phase; a paid plan or topped-up credits add the estimated days until the drop. Days are an estimate, not a promise.\n\nUnits: 1 per page. Works with a free key. MCP tool: list_expiring_domains.","tags":["Market"],"x-dtb-status":"live","x-dtb-units":"1 per page","x-dtb-free":true,"x-dtb-mcp-tool":"list_expiring_domains","parameters":[{"name":"query","in":"query","description":"Keyword to match inside the domain name, e.g. \"coffee\".","schema":{"type":"string"}},{"name":"tld","in":"query","description":"Domain ending without the dot, e.g. \"com\", \"ai\", \"io\".","schema":{"type":"string"}},{"name":"phase","in":"query","description":"grace = just expired, redemption = owner can still restore, pending = about to be deleted.","schema":{"type":"string","enum":["all","grace","redemption","pending"],"default":"all"}},{"name":"max_days","in":"query","description":"Only names estimated to drop within this many days.","schema":{"type":"integer","minimum":0,"maximum":90}},{"name":"query_mode","in":"query","description":"Where query sits in the name.","schema":{"type":"string","enum":["contains","starts_with","ends_with"],"default":"contains"}},{"name":"pattern","in":"query","description":"Name shape, one letter per character: L letter, N digit, C consonant, V vowel (a e i o u). E.g. \"LLL\", \"NNN\", \"LLN\", \"NNL\", \"CVC\", \"CVCV\". Sets the length.","schema":{"type":"string"}},{"name":"mask","in":"query","description":"Fixed characters by position: a-z, 0-9 and - are themselves, ? is any character, and capital L N C V are the classes of pattern. E.g. \"z??\" (3 characters starting with z), \"?a??\", \"ai??\", \"CVCo\". Sets the length and wins over pattern.","schema":{"type":"string"}},{"name":"name_type","in":"query","description":"dictionary = one dictionary word, two_words = two words, brandable = made-up but easy to say (5-8 letters).","schema":{"type":"string","enum":["dictionary","two_words","brandable"]}},{"name":"min_taken_in","in":"query","description":"Only names registered in at least this many endings.","schema":{"type":"integer","minimum":2}},{"name":"min_length","in":"query","description":"Shortest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"max_length","in":"query","description":"Longest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"no_hyphens","in":"query","description":"Leave out names with a hyphen.","schema":{"type":"boolean"}},{"name":"no_numbers","in":"query","description":"Leave out names with a digit.","schema":{"type":"boolean"}},{"name":"min_age","in":"query","description":"Only names first registered at least this many years ago.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"max_age","in":"query","description":"Only names first registered at most this many years ago.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"limit","in":"query","description":"Rows to return. Free answers hold 3 rows; a paid key gets up to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","description":"Page number, paid keys only (free answers are page 1).","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Drop"}}}}]},"example":{"data":[{"domain":"tidy.io","phase":"pending delete","drops_in_days_estimate":3,"age_years":11,"our_estimate":{"value":2400,"low":1100,"high":4800},"url":"https://domaintoolbelt.com/domain/tidy.io"}],"page":1,"limit":25,"total":1284,"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/drops"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/trends/keywords":{"get":{"operationId":"listTrendingKeywords","summary":"Trending keywords","description":"Keywords newly registered across many domain endings in the recent window, a signal of rising demand. A free key gets the top 3, a paid key up to 20.\n\nUnits: 1. Works with a free key. MCP tool: get_trending_keywords.","tags":["Trends"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":true,"x-dtb-mcp-tool":"get_trending_keywords","parameters":[{"name":"window_days","in":"query","description":"Window in days.","schema":{"type":"integer","minimum":1,"maximum":30,"default":7}},{"name":"limit","in":"query","description":"Keywords to return. Free answers hold 3; a paid key gets up to 20.","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrendingKeyword"}}}}]},"example":{"data":[{"keyword":"agentic","endings_registered":64}],"page":1,"limit":25,"total":1284,"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/trends"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/name-atlas":{"get":{"operationId":"searchNameAtlas","summary":"Name Atlas","description":"Names registered in many domain endings, filtered by a keyword, with whether each is in the zone of the ending you target. A name missing from that zone is unconfirmed, not available. A free key gets the top 3 rows; a paid plan or topped-up credits page through up to 100 a page.\n\nUnits: 1 per page. Works with a free key. MCP tool: search_name_atlas.","tags":["Names"],"x-dtb-status":"live","x-dtb-units":"1 per page","x-dtb-free":true,"x-dtb-mcp-tool":"search_name_atlas","parameters":[{"name":"target","in":"query","description":"The ending you want the name in, without the dot, e.g. \"com\" or \"ai\".","schema":{"type":"string"}},{"name":"keyword","in":"query","description":"Only names with this word, e.g. \"shop\".","schema":{"type":"string"}},{"name":"mode","in":"query","description":"Where the keyword sits in the name.","schema":{"type":"string","enum":["starts_with","ends_with","contains"],"default":"contains"}},{"name":"min_taken_in","in":"query","description":"Only names registered in at least this many endings.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"min_length","in":"query","description":"Shortest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"max_length","in":"query","description":"Longest name, without the ending.","schema":{"type":"integer","minimum":1,"maximum":63}},{"name":"letters_only","in":"query","description":"Only names made of letters (no digits or hyphens).","schema":{"type":"boolean"}},{"name":"pattern","in":"query","description":"Name shape, one letter per character: L letter, N digit, C consonant, V vowel (a e i o u). E.g. \"LLL\", \"NNN\", \"LLN\", \"NNL\", \"CVC\", \"CVCV\". Sets the length.","schema":{"type":"string"}},{"name":"mask","in":"query","description":"Fixed characters by position: a-z, 0-9 and - are themselves, ? is any character, and capital L N C V are the classes of pattern. E.g. \"z??\" (3 characters starting with z), \"?a??\", \"ai??\", \"CVCo\". Sets the length and wins over pattern.","schema":{"type":"string"}},{"name":"words","in":"query","description":"Only names that are one word (1) or two words (2).","schema":{"type":"string","enum":["1","2"]}},{"name":"not_in","in":"query","description":"Comma-separated endings the name must not be registered in, e.g. \"net,org\" (up to 20).","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Rows to return. Free answers hold 3 rows; a paid key gets up to 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","description":"Page number, paid keys only (free answers are page 1).","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AtlasName"}}}}]},"example":{"data":[{"name":"shopbox","taken_in":84,"taken_in_major":9,"target_status":"not in the zone (unconfirmed)","url":"https://domaintoolbelt.com/domain/shopbox.ai"}],"page":1,"limit":25,"total":1284,"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/tools/name-atlas"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/emd/{name}":{"get":{"operationId":"getNameAcrossTlds","summary":"Name across endings (EMD)","description":"How many domain endings a name is registered in (its EMD count) and which ones, from registry data, updated within 15 minutes of a fresh appraisal. A free key gets the count and the first 3 endings; a paid plan or topped-up credits list every ending. List endpoints do not carry this number.\n\nUnits: 1. Works with a free key. MCP tool: check_name_across_tlds.","tags":["Names"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":true,"x-dtb-mcp-tool":"check_name_across_tlds","parameters":[{"name":"name","in":"path","required":true,"description":"The name without an ending, e.g. coffee. A full domain also works.","schema":{"type":"string","example":"coffee"}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NameSpread"}}}]},"example":{"data":{"name":"coffee","taken_count":412,"endings":["com","ai","app","biz"],"as_of":"2026-10-31","note":"Endings where the name is registered, from registry data. Not a live check.","url":"https://domaintoolbelt.com/domain/coffee.com"},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/domain/coffee.com"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/availability/bulk":{"post":{"operationId":"bulkAvailability","summary":"Bulk availability","description":"Check up to 500 names in one request. Names on some endings are confirmed more slowly and come back marked unconfirmed first. Needs API Growth or Scale.\n\nUnits: 1 per name. Needs a paid plan or topped-up credits. MCP tool: bulk_check_availability.","tags":["Availability"],"x-dtb-status":"planned","x-dtb-units":"1 per name","x-dtb-free":false,"x-dtb-mcp-tool":"bulk_check_availability","parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500}}},"example":{"domains":["brewly.com","brewly.ai"]}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkResult"}}}]},"example":{"data":{"results":[{"domain":"brewly.com","status":"registered"},{"domain":"brewly.ai","status":"available","confirmed":false}]},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/tools/bulk-availability"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Your usage","description":"Credits used and left this month, today's count and your pack credits.\n\nUnits: 0. Works with a free key.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"0","x-dtb-free":true,"parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Usage"}}}]},"example":{"data":{"plan":"free","addon":null,"tier":"free","month":{"used":312,"limit":10000,"resets_at":"2026-11-01T00:00:00.000Z"},"day":{"used":40,"limit":500,"resets_at":"2026-10-31T00:00:00.000Z"},"queries":{"used":0,"limit":0,"resets_at":"2026-11-01T00:00:00.000Z"},"pack_credits":0,"per_minute":10,"max_rows":3,"by_tool":[{"tool":"search_auctions","units":200},{"tool":"list_expiring_domains","units":112}],"by_channel":{"api":250,"mcp":62},"by_source":[{"channel":"api","kind":"key","label":"Production","units":250},{"channel":"mcp","kind":"app","label":"Claude","units":62}],"daily":[{"day":"2026-10-30","api":120,"mcp":20}]},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/api"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/alerts":{"get":{"operationId":"listAlerts","summary":"Your alerts","description":"Your latest alerts (up to 50) for watched domains and Keyword Watch, newest first, with how many of them are unread. The same alerts as your dashboard and the browser extension.\n\nUnits: 1. Works with a free key. MCP tool: list_alerts.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":true,"x-dtb-mcp-tool":"list_alerts","parameters":[{"name":"unread_only","in":"query","description":"Only alerts you have not read.","schema":{"type":"boolean","default":false}},{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alerts"}}}]},"example":{"data":{"alerts":[{"id":81234,"domain":"tidy.io","title":"Nameservers changed","detail":"Old NS: ns1.old.com\nNew NS: ns1.new.com","at":"2026-10-30T09:12:00Z","read":false}],"unread":1},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/alerts"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/alerts/read":{"post":{"operationId":"markAlertsRead","summary":"Mark alerts read","description":"Mark some of your alerts read, by the ids from GET /alerts, or all of them.\n\nUnits: 1. Works with a free key. MCP tool: mark_alerts_read.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":true,"x-dtb-mcp-tool":"mark_alerts_read","parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"},"maxItems":200},"all":{"type":"boolean"}}},"example":{"ids":[81234]}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertsRead"}}}]},"example":{"data":{"ok":true,"marked":1},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/alerts"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/webhook":{"get":{"operationId":"getWebhook","summary":"Your alert webhook","description":"The HTTPS URL that receives your alerts, whether it is on, and how the last delivery went. The signing secret is never shown here. Set it up in Settings, Notifications, or with PUT /webhook.\n\nUnits: 1. Needs a paid plan or topped-up credits. MCP tool: get_webhook.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":false,"x-dtb-mcp-tool":"get_webhook","parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}]},"example":{"data":{"available":true,"url":"https://hooks.example.com/dtb","enabled":true,"secret_hint":"whsec_…x9Qa","last_success_at":"2026-10-30T09:12:04Z","last_failure_at":null,"last_error":null,"failures_in_a_row":0,"turned_off_after_failures":false,"settings":"https://domaintoolbelt.com/dashboard/settings#webhook"},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/settings#webhook"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}},"put":{"operationId":"setWebhook","summary":"Set your alert webhook","description":"Set the URL, turn the webhook on or off, or rotate the signing secret. The URL must be HTTPS on a public address; redirects are not followed.\n\nThe first call, and any call with regenerate_secret, answers with `secret` once. Keep it with your receiver: it is never shown again.\n\nEach alert is one POST with the JSON body `{ id, type, domain, title, detail, time, link }` and the headers `X-DTB-Event` (alert or test), `X-DTB-Delivery` (the alert id), `X-DTB-Timestamp` (Unix seconds) and `X-DTB-Signature`: `sha256=` + hex HMAC-SHA256 of `{timestamp}.{raw body}` with your secret. Check it, and refuse a timestamp older than 5 minutes.\n\nAnswer with any 2xx within 5 seconds. A failed delivery is tried 3 more times over about an hour. After 20 failed tries in a row the webhook turns off and we email you.\n\nUnits: 1. Needs a paid plan or topped-up credits. MCP tool: set_webhook.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":false,"x-dtb-mcp-tool":"set_webhook","parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"]},"enabled":{"type":"boolean"},"regenerate_secret":{"type":"boolean"}}},"example":{"url":"https://hooks.example.com/dtb","enabled":true}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}]},"example":{"data":{"available":true,"url":"https://hooks.example.com/dtb","enabled":true,"secret_hint":"whsec_…x9Qa","last_success_at":null,"last_failure_at":null,"last_error":null,"failures_in_a_row":0,"turned_off_after_failures":false,"settings":"https://domaintoolbelt.com/dashboard/settings#webhook","secret":"whsec_…","secret_note":"Shown once. Keep it with your receiver."},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/settings#webhook"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}},"/webhook/test":{"post":{"operationId":"testWebhook","summary":"Test your alert webhook","description":"Send one signed test alert (type \"test\") to your webhook URL now and see how it answered. Up to 5 tests in 10 minutes.\n\nUnits: 1. Needs a paid plan or topped-up credits. MCP tool: test_webhook.","tags":["Account"],"x-dtb-status":"live","x-dtb-units":"1","x-dtb-free":false,"x-dtb-mcp-tool":"test_webhook","parameters":[{"name":"DTB-Version","in":"header","required":false,"description":"Optional. Lock the answer shape to a dated version; without it you get the latest (2026-11-01).","schema":{"type":"string","enum":["2026-11-01"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookTest"}}}]},"example":{"data":{"ok":true,"status":204,"error":null,"at":"2026-10-30T09:12:04Z"},"as_of":"2026-10-30T14:00:00Z","link":"https://domaintoolbelt.com/dashboard/settings#webhook"}}}},"400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"bad_request","message":"A parameter is missing or not valid. The message says which one."}}}}},"401":{"description":"missing_key, invalid_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"missing_key","message":"No key was sent. Add the Authorization header."}}}}},"403":{"description":"email_unverified, plan_required, account_frozen, read_only_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"email_unverified","message":"Verify your email address to use a free key."}}}}},"429":{"description":"rate_limited, daily_limit, monthly_quota, service_busy, ip_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many calls this minute (data queries: 10 a minute on every plan). Wait for Retry-After seconds."}}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unavailable","message":"The service is paused for a moment. Try again shortly."}}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","bearerFormat":"dtb_live_ followed by 32 letters and digits","description":"Authorization: Bearer dtb_live_... (X-API-Key is also accepted)."}},"schemas":{"Envelope":{"type":"object","required":["data","as_of","link"],"properties":{"data":{"description":"The answer: one object or a list of rows."},"page":{"type":"integer","description":"Lists only."},"limit":{"type":"integer","description":"Lists only."},"total":{"type":"integer","description":"Lists only: rows that match."},"as_of":{"type":"string","format":"date-time","description":"When the data was last updated."},"link":{"type":"string","format":"uri","description":"The matching domaintoolbelt.com page. Cite it."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","missing_key","invalid_key","email_unverified","plan_required","account_frozen","read_only_key","not_found","rate_limited","daily_limit","monthly_quota","service_busy","ip_limit","unavailable"]},"message":{"type":"string"},"doc_url":{"type":"string","format":"uri","description":"The code explained on the errors page."},"request_id":{"type":"string","description":"This call's id (also the X-Request-Id header). Quote it if you contact us."}}},"link":{"type":"string","format":"uri","description":"Where to fix it, e.g. the upgrade page."}}},"DomainStatus":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["available","registered","registered, for sale","unknown"]},"for_sale":{"type":["object","null"],"properties":{"marketplace":{"type":"string"},"price":{"type":["number","null"]},"currency":{"type":"string"}}},"checked":{"type":"string","enum":["stored","live"]},"url":{"type":"string","format":"uri"}}},"DomainSummary":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"for_sale":{"type":["object","null"]},"in_auction":{"type":["object","null"]},"last_sale":{"type":["object","null"],"properties":{"price":{"type":"number"},"currency":{"type":"string"},"date":{"type":["string","null"]},"venue":{"type":["string","null"]}}},"sales_count":{"type":"integer","description":"Paid keys only."},"sales":{"type":"array","description":"Paid keys only: price and year of every sale, newest first. reported = an unconfirmed claim.","items":{"type":"object","properties":{"price":{"type":"number"},"currency":{"type":"string"},"year":{"type":["integer","null"]},"reported":{"type":"boolean"}}}},"estimate":{"type":["object","null"],"description":"Our stored value estimate in USD, or null.","properties":{"value":{"type":"number"},"low":{"type":["number","null"]},"high":{"type":["number","null"]},"currency":{"type":"string"}}},"registered_since":{"type":["integer","null"]},"note":{"type":"string"},"url":{"type":"string","format":"uri"}}},"DomainTimeline":{"type":"object","properties":{"domain":{"type":"string"},"sales_count":{"type":"integer"},"sales":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number"},"currency":{"type":"string"},"date":{"type":["string","null"],"description":"YYYY-MM or YYYY."},"venue":{"type":["string","null"]},"reported":{"type":"boolean"}}}},"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"date":{"type":["string","null"],"format":"date"},"marketplace":{"type":"string"},"price":{"type":"number"}}}},"url":{"type":"string","format":"uri"}}},"Appraisal":{"type":"object","properties":{"domain":{"type":"string"},"estimate":{"type":["object","null"],"description":"Our stored value estimate in USD, or null.","properties":{"value":{"type":"number"},"low":{"type":["number","null"]},"high":{"type":["number","null"]},"currency":{"type":"string"},"computed_at":{"type":"string","format":"date-time"}}},"note":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Sale":{"type":"object","properties":{"domain":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"sale_date":{"type":"string","format":"date"},"venue":{"type":["string","null"]},"reported":{"type":"boolean","description":"true = a venue reported it; false = we spotted it ourselves."},"url":{"type":"string","format":"uri"}}},"Auction":{"type":"object","properties":{"domain":{"type":"string"},"marketplace":{"type":["string","null"]},"current_bid":{"type":["number","null"]},"currency":{"type":"string"},"bids":{"type":["integer","null"]},"ends_at":{"type":["string","null"],"format":"date-time"},"type":{"type":["string","null"]},"our_estimate":{"type":["object","null"],"description":"Our stored value estimate in USD, or null.","properties":{"value":{"type":"number"},"low":{"type":["number","null"]},"high":{"type":["number","null"]},"currency":{"type":"string"}}},"url":{"type":"string","format":"uri"}}},"Drop":{"type":"object","properties":{"domain":{"type":"string"},"phase":{"type":["string","null"]},"drops_in_days_estimate":{"type":["integer","null"],"description":"Add-on only. An estimate, not a promise."},"age_years":{"type":["number","null"]},"our_estimate":{"type":["object","null"],"description":"Our stored value estimate in USD, or null.","properties":{"value":{"type":"number"},"low":{"type":["number","null"]},"high":{"type":["number","null"]},"currency":{"type":"string"}}},"url":{"type":"string","format":"uri"}}},"TrendingKeyword":{"type":"object","properties":{"keyword":{"type":"string"},"endings_registered":{"type":["integer","null"]}}},"AtlasName":{"type":"object","properties":{"name":{"type":"string"},"taken_in":{"type":"integer","description":"Endings the name is registered in."},"taken_in_major":{"type":"integer","description":"Of those, the big endings."},"target_status":{"type":"string","enum":["taken","not in the zone (unconfirmed)"]},"url":{"type":"string","format":"uri"}}},"NameSpread":{"type":"object","properties":{"name":{"type":"string"},"taken_count":{"type":"integer"},"endings":{"type":"array","items":{"type":"string"},"description":"Free keys: the first 3 (.com first, then A to Z). Paid: every ending."},"endings_shown":{"type":"integer","description":"Present when the list is cut."},"more_endings":{"type":"string"},"as_of":{"type":["string","null"],"description":"Date of the data."},"note":{"type":"string"},"url":{"type":"string","format":"uri"}}},"BulkResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"confirmed":{"type":"boolean"}}}}}},"Usage":{"type":"object","properties":{"plan":{"type":"string","description":"free, pro, business, lifetime or owner."},"addon":{"type":["string","null"],"enum":["starter","growth","scale",null]},"tier":{"type":"string","enum":["free","paid"]},"month":{"$ref":"#/components/schemas/UsagePeriod"},"day":{"$ref":"#/components/schemas/UsagePeriod"},"queries":{"$ref":"#/components/schemas/UsagePeriod","description":"Data queries (status, summary, history, sales pages) this month. Past the limit each takes 20 topped-up credits."},"pack_credits":{"type":"integer","description":"One-time pack credits left. They never expire and are used after the monthly credits run out."},"per_minute":{"type":"integer"},"max_rows":{"type":"integer"},"by_tool":{"type":"array","description":"Credits per tool this month; for the four data tools, data queries.","items":{"type":"object","properties":{"tool":{"type":"string"},"units":{"type":"integer"}}}},"by_channel":{"type":"object","description":"This month by door: REST API calls vs MCP (AI assistant) calls.","properties":{"api":{"type":"integer"},"mcp":{"type":"integer"}}},"by_source":{"type":"array","description":"This month by API key name or connected AI app.","items":{"type":"object","properties":{"channel":{"type":"string","enum":["api","mcp"]},"kind":{"type":"string","enum":["key","app"]},"label":{"type":"string"},"units":{"type":"integer"}}}},"daily":{"type":"array","description":"Last 30 UTC days, API vs MCP units per day.","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"api":{"type":"integer"},"mcp":{"type":"integer"}}}}}},"Webhook":{"type":"object","properties":{"available":{"type":"boolean","description":"false on a plan without webhooks."},"url":{"type":["string","null"],"format":"uri"},"enabled":{"type":"boolean"},"secret_hint":{"type":["string","null"]},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":["string","null"]},"failures_in_a_row":{"type":"integer"},"turned_off_after_failures":{"type":"boolean"},"settings":{"type":"string","format":"uri"},"secret":{"type":"string","description":"Only when this call created or rotated it."},"secret_note":{"type":"string"}}},"WebhookTest":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["integer","null"],"description":"Your endpoint's HTTP status."},"error":{"type":["string","null"]},"at":{"type":"string","format":"date-time"}}},"Alerts":{"type":"object","properties":{"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"domain":{"type":["string","null"]},"title":{"type":["string","null"]},"detail":{"type":["string","null"]},"at":{"type":["string","null"],"format":"date-time"},"read":{"type":"boolean"}}}},"unread":{"type":"integer","description":"Unread among the alerts returned."}}},"AlertsRead":{"type":"object","properties":{"ok":{"type":"boolean"},"marked":{"description":"How many were marked, or \"all\".","type":["integer","string"]}}},"UsagePeriod":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":["integer","null"],"description":"null = no cap."},"resets_at":{"type":"string","format":"date-time"}}}}}}