{"openapi":"3.1.0","info":{"title":"top1m public API","version":"1.0.0","description":"Anonymous public read API. Snapshot metadata accompanies ranking datasets."},"paths":{"/api/v1/rankings":{"get":{"operationId":"ApiV1Rankings","summary":"Search current or dated domain rankings. Selective current filters return a lower-bound total and hasMore instead of running an expensive exact count.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/rankings/export":{"get":{"operationId":"ApiV1RankingsExport","summary":"Redirect to the latest immutable domain-ranking gzip CSV archive (1M or broader current 10M edition).","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts":{"get":{"operationId":"ApiV1Hosts","summary":"Browse current hostname rankings.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts/export":{"get":{"operationId":"ApiV1HostsExport","summary":"Redirect to the latest immutable hostname-ranking gzip CSV archive (1M or broader current 10M edition).","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/ips":{"get":{"operationId":"ApiV1Ips","summary":"Browse all-observed IPv4 or IPv6 rankings ordered by observation hits and recency.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/ips/export":{"get":{"operationId":"ApiV1IpsExport","summary":"Redirect to the latest immutable Top-1M IPv4 or IPv6 gzip CSV archive, ordered by hits.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}":{"get":{"operationId":"ApiV1DomainsName","summary":"Get a current domain profile and rank.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}/history":{"get":{"operationId":"ApiV1DomainsNameHistory","summary":"Get published daily rank history.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/bulk-lookup":{"post":{"operationId":"ApiV1DomainsBulkLookup","summary":"Compare up to 1,000 domains without modifying the index.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/search":{"get":{"operationId":"ApiV1Search","summary":"Search indexed domain names and observed URLs.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}/urls":{"get":{"operationId":"ApiV1DomainsNameUrls","summary":"List URLs observed on a domain's hosts.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}/connections":{"get":{"operationId":"ApiV1DomainsNameConnections","summary":"Pivot between a domain, resource-provider domains, loading domains, and ordinary hyperlinks.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/technologies":{"get":{"operationId":"ApiV1Technologies","summary":"Browse current technologies ranked by observed domain count (scope=1m; other scopes return unsupported_scope).","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/tech/{slug}":{"get":{"operationId":"ApiV1TechSlug","summary":"Get a current technology profile and exact observed domain count, with up to 10,000 ranked domain examples.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/contacts":{"get":{"operationId":"ApiV1Contacts","summary":"Search observed public email and phone signals.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/contacts/{value}/domains":{"get":{"operationId":"ApiV1ContactsValueDomains","summary":"Find ranked domains associated with a contact signal.","parameters":[{"name":"value","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/lists":{"get":{"operationId":"ApiV1Lists","summary":"List current public web-observable leaderboards.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/lists/{type}":{"get":{"operationId":"ApiV1ListsType","summary":"Browse a current Top-1M supporting list. Canonical crypto views use wallet names and analytics views may be provider-specific; legacy *_addresses API types remain compatible.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/lists/{type}/export":{"get":{"operationId":"ApiV1ListsTypeExport","summary":"Export up to 100,000 current list rows as CSV. Wallet and provider-specific views are aliases over the current published generation.","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/observables/{id}":{"get":{"operationId":"ApiV1ObservablesId","summary":"Get a non-URL supporting-list observable and its current usage statistics.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/observables/{id}/domains":{"get":{"operationId":"ApiV1ObservablesIdDomains","summary":"Get a bounded top-ranked domain sample currently associated with a non-URL observable.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/observables/{id}/hosts":{"get":{"operationId":"ApiV1ObservablesIdHosts","summary":"Get a bounded top-ranked host sample currently associated with a non-URL observable.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/urls":{"get":{"operationId":"ApiV1Urls","summary":"Search observed URLs across supported URL types.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/urls/{id}":{"get":{"operationId":"ApiV1UrlsId","summary":"Get an observed URL profile with bounded source and technology pivots.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/urls/{id}/domains":{"get":{"operationId":"ApiV1UrlsIdDomains","summary":"Find ranked domains observed using a URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/urls/{id}/hosts":{"get":{"operationId":"ApiV1UrlsIdHosts","summary":"Find ranked hosts observed using a URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts/{fqdn}/urls":{"get":{"operationId":"ApiV1HostsFqdnUrls","summary":"List URLs observed on a hostname.","parameters":[{"name":"fqdn","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/analytics":{"get":{"operationId":"ApiV1Analytics","summary":"Search observed analytics identifiers with an optional provider filter.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/analytics/{id}":{"get":{"operationId":"ApiV1AnalyticsId","summary":"Get an observed analytics identifier and bounded usage statistics.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/analytics/{id}/domains":{"get":{"operationId":"ApiV1AnalyticsIdDomains","summary":"Find ranked domains observed with an analytics identifier.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/analytics/{id}/hosts":{"get":{"operationId":"ApiV1AnalyticsIdHosts","summary":"Find ranked hosts observed with an analytics identifier.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}/analytics":{"get":{"operationId":"ApiV1DomainsNameAnalytics","summary":"List analytics identifiers observed on a domain.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts/{fqdn}/analytics":{"get":{"operationId":"ApiV1HostsFqdnAnalytics","summary":"List analytics identifiers observed on a hostname.","parameters":[{"name":"fqdn","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/domains/{name}/observables":{"get":{"operationId":"ApiV1DomainsNameObservables","summary":"List current non-URL observables, including wallets and markup signals, associated with a domain.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts/{fqdn}/observables":{"get":{"operationId":"ApiV1HostsFqdnObservables","summary":"List current non-URL observables associated with a hostname.","parameters":[{"name":"fqdn","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/dns/{rrtype}/{value}":{"get":{"operationId":"ApiV1DnsRrtypeValue","summary":"Get retained MX or NS observation statistics for an exact server name.","parameters":[{"name":"rrtype","in":"path","required":true,"schema":{"type":"string"}},{"name":"value","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/dns/{rrtype}/{value}/domains":{"get":{"operationId":"ApiV1DnsRrtypeValueDomains","summary":"Find ranked domains observed using an exact MX or NS server.","parameters":[{"name":"rrtype","in":"path","required":true,"schema":{"type":"string"}},{"name":"value","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/dns/{rrtype}/{value}/hosts":{"get":{"operationId":"ApiV1DnsRrtypeValueHosts","summary":"Find ranked hostnames observed using an exact MX or NS server.","parameters":[{"name":"rrtype","in":"path","required":true,"schema":{"type":"string"}},{"name":"value","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/hosts/{fqdn}":{"get":{"operationId":"ApiV1HostsFqdn","summary":"Get a current hostname profile and rank.","parameters":[{"name":"fqdn","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/whois/{name}":{"get":{"operationId":"ApiV1WhoisName","summary":"Return the latest available cached WHOIS profile.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/links/{name}":{"get":{"operationId":"ApiV1LinksName","summary":"Return current inbound and outbound crawl links.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/pdns/{name}":{"get":{"operationId":"ApiV1PdnsName","summary":"Return observed DNS records for a domain.","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/pdns/ip/{ip}":{"get":{"operationId":"ApiV1PdnsIpIp","summary":"Find domains observed on an IP address.","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/ips/{address}":{"get":{"operationId":"ApiV1IpsAddress","summary":"Get an IP profile and hosted-domain observations.","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/expired":{"get":{"operationId":"ApiV1Expired","summary":"Browse previously ranked domains explicitly confirmed absent by a registry.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/expired/export":{"get":{"operationId":"ApiV1ExpiredExport","summary":"Export registry-confirmed expired domains.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/renewed":{"get":{"operationId":"ApiV1Renewed","summary":"Browse names observed registered again after a confirmed absence.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/renewed/export":{"get":{"operationId":"ApiV1RenewedExport","summary":"Export the compact re-registered-domain transition ledger.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/expiring":{"get":{"operationId":"ApiV1Expiring","summary":"Browse previously ranked domains approaching or passing their expected expiry.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/expiring/export":{"get":{"operationId":"ApiV1ExpiringExport","summary":"Export current expiring-domain candidates.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/exports":{"get":{"operationId":"ApiV1Exports","summary":"List immutable daily archive files and checksums.","parameters":[],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}},"/api/v1/exports/{dataset}/{scope}/{edition}":{"get":{"operationId":"ApiV1ExportsDatasetScopeEdition","summary":"Download a latest or immutable dated ranking archive. Dataset is domains, hosts, ipv4, or ipv6; edition is latest or YYYYMMDD.","parameters":[{"name":"dataset","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"path","required":true,"schema":{"type":"string"}},{"name":"edition","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response"},"400":{"description":"Invalid request"},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Temporarily unavailable"}}}}}}