{"openapi":"3.1.0","info":{"title":"BeforeYouRegister API","version":"1.0.0","description":"Machine-readable REST and MCP API for domain price comparison, real-time availability checking, RDAP WHOIS queries, and DNS inspection. All quotes include mandatory $0.18 ICANN fees with transparent 3-year total ownership calculations. No sponsored ranking bias.","contact":{"name":"BeforeYouRegister","url":"https://beforeyouregister.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://beforeyouregister.com","description":"Current environment server"},{"url":"https://beforeyouregister.com","description":"Production server"},{"url":"http://localhost:3000","description":"Local development server"}],"tags":[{"name":"TLD Pricing","description":"Query TLD best prices, multi-registrar comparisons, and full A-Z directories."},{"name":"Registrars","description":"Ranked registrar leaderboard and transparency scoring."},{"name":"Availability","description":"Real-time domain availability checks via DoH and RDAP registries."},{"name":"Research","description":"Authoritative RDAP WHOIS lookups and live DNS record inspector."},{"name":"AI Agents & MCP","description":"Model Context Protocol (MCP) server endpoints for autonomous agents."},{"name":"Redirection","description":"Outbound affiliate routing and deep-linking."}],"paths":{"/api/tlds":{"get":{"tags":["TLD Pricing"],"summary":"List best prices for TLDs","description":"Returns a paginated list of top-level domain extensions with their lowest registration, renewal, and 3-year total prices across tracked registrars. All prices include the $0.18 ICANN fee on gTLDs.","operationId":"listTldBestPrices","parameters":[{"name":"q","in":"query","description":"Filter extensions or tags by keyword (e.g. \"com\", \"tech\", \"cloud\")","schema":{"type":"string"}},{"name":"letter","in":"query","description":"Filter by starting letter (a-z or \"all\")","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by category: all, popular, gtld, cctld","schema":{"type":"string","default":"all"}},{"name":"registrar","in":"query","description":"Filter by winning registrar slug (e.g. \"porkbun\", \"spaceship\", \"cloudflare\")","schema":{"type":"string"}},{"name":"trap","in":"query","description":"Filter by renewal trap status: \"yes\" for trapped TLDs, \"no\" for safe TLDs","schema":{"type":"string","enum":["yes","no"]}},{"name":"tag","in":"query","description":"Filter by use-case topic tag (e.g. \"developer\", \"startup\", \"ecommerce\")","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort field: popular, reg, renew, transfer, total, rating, alpha","schema":{"type":"string","enum":["popular","reg","renew","transfer","total","rating","alpha"],"default":"popular"}},{"name":"order","in":"query","description":"Sort order: asc or desc","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}},{"name":"page","in":"query","description":"Page number (1-based)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","description":"Items per page (max 250)","schema":{"type":"integer","default":50,"minimum":1,"maximum":250}}],"responses":{"200":{"description":"Successful query returning TLD pricing rows and pagination metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldListResponse"}}}},"400":{"description":"Invalid query parameters (e.g. invalid sort or pagination).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/tld/{ext}":{"get":{"tags":["TLD Pricing"],"summary":"Get full registrar price breakdown for a single TLD","description":"Returns detailed quotes across all tracked registrars for a single TLD extension (e.g. com, ai, org), including first-year, renewal, transfer, 3-year and 5-year totals, WHOIS privacy status, and renewal trap flags.","operationId":"getTldDetail","parameters":[{"name":"ext","in":"path","required":true,"description":"TLD extension without leading dot (e.g. \"com\", \"ai\", \"dev\")","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number for registrar quotes (1-based)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","description":"Quotes per page (max 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Detailed multi-registrar quotes for the specified TLD.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldDetailResponse"}}}},"404":{"description":"TLD extension not found in registry database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/tlds/a-z":{"get":{"tags":["TLD Pricing"],"summary":"Browse complete 898+ A-Z TLD catalog","description":"Returns the full catalog of all 898+ top-level domain extensions recognized by ICANN and IANA with classification types and registry managers.","operationId":"listTldsAz","parameters":[{"name":"q","in":"query","description":"Filter extensions by substring","schema":{"type":"string"}},{"name":"type","in":"query","description":"Filter by extension type: generic, country-code, sponsored, infrastructure","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (1-based)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","description":"Items per page (max 500)","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Paginated list of TLDs from the A-Z directory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AzListResponse"}}}}}}},"/api/registrars":{"get":{"tags":["Registrars"],"summary":"Ranked registrar leaderboard","description":"Returns all 10 domain registrars ranked by BeforeYouRegister transparency score, 3-year average cost, renewal trap frequency, free WHOIS privacy, and Trustpilot sentiment.","operationId":"listRegistrars","parameters":[{"name":"sort","in":"query","description":"Sorting criteria: rating, wins, trust, price","schema":{"type":"string","enum":["rating","wins","trust","price"],"default":"rating"}},{"name":"free_whois","in":"query","description":"Filter to only registrars offering 100% free WHOIS privacy","schema":{"type":"boolean"}},{"name":"page","in":"query","description":"Page number (1-based)","schema":{"type":"integer","default":1,"minimum":1}},{"name":"size","in":"query","description":"Registrars per page (max 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of scored registrars with metrics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarLeaderboardResponse"}}}}}}},"/api/availability":{"get":{"tags":["Availability"],"summary":"Check real-time domain availability","description":"Queries DNS-over-HTTPS (DoH) via Cloudflare 1.1.1.1 and authoritative RDAP registry endpoints to determine domain status (available, taken, premium, or unknown) with transparent multi-year pricing.","operationId":"checkAvailability","parameters":[{"name":"domain","in":"query","required":true,"description":"Full domain name to check (e.g. \"mycoffeestudio.com\", \"neuralflow.ai\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Availability resolution with source, latency, and pricing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResult"}}}},"400":{"description":"Missing or invalid domain parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Upstream registry or DNS lookup failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/availability/batch":{"post":{"tags":["Availability"],"summary":"Bulk check multiple domains","description":"Checks availability concurrently for up to 30 domains with rate-limiting and deduplication.","operationId":"checkAvailabilityBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"List of domain names (up to 30)","maxItems":30}},"required":["domains"]}}}},"responses":{"200":{"description":"Array of availability results.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilityResult"}}}}}}},"400":{"description":"Empty or invalid domains list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/whois":{"get":{"tags":["Research"],"summary":"Query authoritative RDAP WHOIS registry","description":"Queries official IANA-delegated RDAP servers for structured domain registration dates, registrar of record, expiration date, name servers, and domain statuses.","operationId":"lookupWhois","parameters":[{"name":"domain","in":"query","required":true,"description":"Domain name to query (e.g. \"github.com\", \"openai.com\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Structured RDAP WHOIS record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoisRecord"}}}},"400":{"description":"Invalid domain name or RDAP lookup error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/dns":{"get":{"tags":["Research"],"summary":"Live DNS-over-HTTPS record inspection","description":"Inspects real-time DNS records (A, AAAA, MX, TXT, NS, CNAME, SOA) via Cloudflare DNS-over-HTTPS with TTL and status codes.","operationId":"lookupDns","parameters":[{"name":"domain","in":"query","required":true,"description":"Domain name to inspect (e.g. \"stripe.com\")","schema":{"type":"string"}},{"name":"type","in":"query","description":"DNS record type (A, AAAA, MX, TXT, NS, CNAME, SOA, or ALL)","schema":{"type":"string","enum":["ALL","A","AAAA","MX","TXT","NS","CNAME","SOA"],"default":"ALL"}}],"responses":{"200":{"description":"Resolved DNS records and query metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsResponse"}}}},"400":{"description":"Invalid domain parameter or DNS resolution failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/mcp":{"get":{"tags":["AI Agents & MCP"],"summary":"Get Model Context Protocol server metadata","description":"Returns MCP protocol version, server identity, and the catalog of callable tools for AI agents.","operationId":"getMcpMetadata","responses":{"200":{"description":"MCP server metadata and tools list."}}},"post":{"tags":["AI Agents & MCP"],"summary":"Execute Model Context Protocol JSON-RPC method","description":"Executes MCP JSON-RPC 2.0 requests such as \"initialize\", \"tools/list\", and \"tools/call\" (check_availability, search_tlds, compare_registrars, get_registrar_leaderboard, generate_variations, lookup_whois, lookup_dns).","operationId":"handleMcpRpc","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":["string","number"]},"method":{"type":"string","example":"tools/call"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC response containing tool output or error."}}}},"/go/{registrar}":{"get":{"tags":["Redirection"],"summary":"Outbound affiliate redirect gateway","description":"Resolves approved registrar partner affiliate deep links while preserving transparent domain parameters and zero user price markup. Fire-and-forget attribution tracking.","operationId":"resolveAffiliateRedirect","parameters":[{"name":"registrar","in":"path","required":true,"description":"Registrar slug (e.g. spaceship, dynadot, namecheap, namesilo, netim, porkbun, cloudflare)","schema":{"type":"string"}},{"name":"tld","in":"query","description":"Target TLD extension without dot (e.g. \"com\", \"ai\")","schema":{"type":"string"}},{"name":"domain","in":"query","description":"Full domain name to search or purchase on registrar checkout","schema":{"type":"string"}},{"name":"promo","in":"query","description":"Optional promo code to auto-apply at registrar checkout","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirects browser or agent to official registrar checkout URL."},"404":{"description":"Unknown registrar slug."}}}}},"components":{"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"size":{"type":"integer"},"totalItems":{"type":"integer"},"totalPages":{"type":"integer"},"hasNextPage":{"type":"boolean"},"hasPrevPage":{"type":"boolean"}},"required":["page","size","totalItems","totalPages","hasNextPage","hasPrevPage"]},"TldBestPrice":{"type":"object","properties":{"extension":{"type":"string","example":"com"},"category":{"type":"string","example":"gtld"},"popularity_rank":{"type":"integer","example":1},"best_reg_price":{"type":"number","example":10.28},"best_reg_registrar_slug":{"type":"string","example":"spaceship"},"best_reg_registrar_name":{"type":"string","example":"Spaceship"},"best_renew_price":{"type":"number","example":10.28},"best_renew_registrar_slug":{"type":"string","example":"spaceship"},"best_renew_registrar_name":{"type":"string","example":"Spaceship"},"best_3yr_total":{"type":"number","example":30.84},"best_3yr_registrar_slug":{"type":"string","example":"spaceship"},"best_3yr_registrar_name":{"type":"string","example":"Spaceship"},"has_renewal_trap_on_cheapest":{"type":"boolean","example":false},"renewal_trap_multiplier":{"type":["number","null"],"example":1},"icann_fee_included":{"type":"boolean","example":true},"free_whois_privacy":{"type":"boolean","example":true},"tags":{"type":"array","items":{"type":"string"}}},"required":["extension","category","best_reg_price","best_renew_price","best_3yr_total","best_3yr_registrar_name","has_renewal_trap_on_cheapest"]},"TldListResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string","format":"date-time"},"count":{"type":"integer"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"tlds":{"type":"array","items":{"$ref":"#/components/schemas/TldBestPrice"}}},"required":["lastUpdatedAt","count","pagination","tlds"]},"RegistrarQuote":{"type":"object","properties":{"registrar_slug":{"type":"string"},"registrar_name":{"type":"string"},"total_reg_price":{"type":"number"},"total_renew_price":{"type":"number"},"total_transfer_price":{"type":"number"},"three_year_total":{"type":"number"},"five_year_total":{"type":"number"},"free_whois_privacy":{"type":"boolean"},"trustpilot_score":{"type":"number"},"is_renewal_trap":{"type":"boolean"},"renewal_spike_multiplier":{"type":"number"},"promo_code":{"type":["string","null"]}},"required":["registrar_slug","registrar_name","total_reg_price","total_renew_price","three_year_total","free_whois_privacy","is_renewal_trap"]},"TldDetailResponse":{"type":"object","properties":{"tld":{"type":"object","properties":{"extension":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"registry_operator":{"type":"string"}}},"summary":{"type":"object","properties":{"lowest_reg":{"type":"number"},"lowest_renew":{"type":"number"},"lowest_3yr":{"type":"number"},"best_registrar":{"type":"string"}}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarQuote"}}},"required":["tld","quotes"]},"AzListResponse":{"type":"object","properties":{"total":{"type":"integer"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"items":{"type":"array","items":{"type":"object","properties":{"extension":{"type":"string"},"type":{"type":"string"},"manager":{"type":"string"},"description":{"type":"string"}}}}},"required":["total","pagination","items"]},"RegistrarScoreCard":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"rating_score":{"type":"number"},"rating_stars":{"type":"number"},"cheapest_tld_count":{"type":"integer"},"trap_tld_count":{"type":"integer"},"free_whois_privacy":{"type":"boolean"},"trustpilot_score":{"type":"number"},"avg_3yr_total":{"type":"number"}},"required":["slug","name","rating_score","cheapest_tld_count","trap_tld_count","free_whois_privacy"]},"RegistrarLeaderboardResponse":{"type":"object","properties":{"lastUpdatedAt":{"type":"string"},"count":{"type":"integer"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"topRegistrar":{"$ref":"#/components/schemas/RegistrarScoreCard"},"registrars":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarScoreCard"}}},"required":["lastUpdatedAt","count","pagination","registrars"]},"AvailabilityResult":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["available","taken","premium","unknown"]},"source":{"type":"string","enum":["doh","rdap","fallback"]},"latencyMs":{"type":"integer"},"tldPrices":{"$ref":"#/components/schemas/TldBestPrice"},"alternatives":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"}}}}},"required":["domain","status","source","latencyMs"]},"WhoisRecord":{"type":"object","properties":{"domain":{"type":"string"},"registrar":{"type":"string"},"registrationDate":{"type":"string"},"expirationDate":{"type":"string"},"lastUpdatedDate":{"type":"string"},"nameServers":{"type":"array","items":{"type":"string"}},"domainStatus":{"type":"array","items":{"type":"string"}},"dnssec":{"type":"boolean"},"privacyProtected":{"type":"boolean"}},"required":["domain","registrar"]},"DnsResponse":{"type":"object","properties":{"domain":{"type":"string"},"type":{"type":"string"},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"},"TTL":{"type":"integer"}}}}},"required":["domain","records"]}}}}