{"openapi":"3.1.0","info":{"title":"Bitcoin Node Atlas API","description":"Public API for reachable Bitcoin nodes, advertised unreachable nodes, and observed address statistics.","version":"0.1.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/stats":{"get":{"summary":"Stats","operationId":"stats_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}},"/nodes":{"get":{"summary":"Nodes","operationId":"nodes_nodes_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":250,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["reachable","unreachable","stale"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"network_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["ipv4","ipv6","onion","tor"],"type":"string"},{"type":"null"}],"title":"Network Type"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/nodes/{node_id}":{"get":{"summary":"Node Detail","operationId":"node_detail_nodes__node_id__get","parameters":[{"name":"node_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Node Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NodeDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check-node":{"post":{"summary":"Check Node","operationId":"check_node_check_node_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckNodeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckNodeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/versions":{"get":{"summary":"Versions","operationId":"versions_versions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/VersionBreakdown"},"type":"array","title":"Response Versions Versions Get"}}}}}}},"/countries":{"get":{"summary":"Countries","operationId":"countries_countries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CountryBreakdown"},"type":"array","title":"Response Countries Countries Get"}}}}}}},"/map-data":{"get":{"summary":"Map Data","operationId":"map_data_map_data_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["all","reachable"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"network_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["all","ipv4","ipv6","onion","tor"],"type":"string"},{"type":"null"}],"title":"Network Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MapDataResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CheckNodeRequest":{"properties":{"host":{"type":"string","maxLength":253,"minLength":1,"title":"Host"},"port":{"type":"integer","maximum":65535.0,"minimum":1.0,"title":"Port","default":8333}},"type":"object","required":["host"],"title":"CheckNodeRequest","examples":[{"host":"8.8.8.8","port":8333},{"host":"[2001:4860:4860::8888]:8333","port":8333},{"host":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.onion","port":8333}]},"CheckNodeResponse":{"properties":{"host":{"type":"string","title":"Host"},"checked_address":{"type":"string","title":"Checked Address"},"port":{"type":"integer","title":"Port"},"network_type":{"type":"string","title":"Network Type"},"reachable":{"type":"boolean","title":"Reachable"},"status":{"type":"string","title":"Status"},"checked_at":{"type":"string","format":"date-time","title":"Checked At"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"protocol_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Protocol Version"},"services":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Services"},"start_height":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Start Height"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["host","checked_address","port","network_type","reachable","status","checked_at","latency_ms","user_agent","protocol_version","services","start_height","error_code","error"],"title":"CheckNodeResponse"},"CountryBreakdown":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"reachable_nodes":{"type":"integer","title":"Reachable Nodes"},"observed_nodes":{"type":"integer","title":"Observed Nodes"},"percentage":{"type":"number","title":"Percentage"}},"type":"object","required":["country","country_code","reachable_nodes","observed_nodes","percentage"],"title":"CountryBreakdown"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MapDataResponse":{"properties":{"points":{"items":{"$ref":"#/components/schemas/MapPoint"},"type":"array","title":"Points"},"unknown":{"$ref":"#/components/schemas/MapUnknownBucket"}},"type":"object","required":["points","unknown"],"title":"MapDataResponse"},"MapNetworkTypes":{"properties":{"ipv4":{"type":"integer","title":"Ipv4"},"ipv6":{"type":"integer","title":"Ipv6"},"onion":{"type":"integer","title":"Onion"}},"type":"object","required":["ipv4","ipv6","onion"],"title":"MapNetworkTypes"},"MapPoint":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"reachable_count":{"type":"integer","title":"Reachable Count"},"observed_count":{"type":"integer","title":"Observed Count"},"network_types":{"$ref":"#/components/schemas/MapNetworkTypes"}},"type":"object","required":["country","country_code","region","city","latitude","longitude","reachable_count","observed_count","network_types"],"title":"MapPoint"},"MapUnknownBucket":{"properties":{"reachable_count":{"type":"integer","title":"Reachable Count"},"observed_count":{"type":"integer","title":"Observed Count"}},"type":"object","required":["reachable_count","observed_count"],"title":"MapUnknownBucket"},"NodeDetail":{"properties":{"id":{"type":"integer","title":"Id"},"address":{"type":"string","title":"Address"},"port":{"type":"integer","title":"Port"},"network_type":{"type":"string","title":"Network Type"},"status":{"type":"string","title":"Status"},"protocol_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Protocol Version"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"services":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Services"},"start_height":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Start Height"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"asn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Asn"},"network_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Network Name"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At"},"first_observed_at":{"type":"string","format":"date-time","title":"First Observed At"},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Seen At"}},"type":"object","required":["id","address","port","network_type","status","protocol_version","user_agent","services","start_height","latency_ms","last_checked_at","first_observed_at","last_seen_at"],"title":"NodeDetail"},"NodeListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/NodeSummary"},"type":"array","title":"Items"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["items","limit","offset","total"],"title":"NodeListResponse"},"NodeSummary":{"properties":{"id":{"type":"integer","title":"Id"},"address":{"type":"string","title":"Address"},"port":{"type":"integer","title":"Port"},"network_type":{"type":"string","title":"Network Type"},"status":{"type":"string","title":"Status"},"protocol_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Protocol Version"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"services":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Services"},"start_height":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Start Height"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country Code"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"asn":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Asn"},"network_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Network Name"},"last_checked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked At"}},"type":"object","required":["id","address","port","network_type","status","protocol_version","user_agent","services","start_height","latency_ms","last_checked_at"],"title":"NodeSummary"},"StatsResponse":{"properties":{"reachable_nodes":{"type":"integer","title":"Reachable Nodes","description":"Nodes that accepted a recent reachability check."},"advertised_unreachable_nodes":{"type":"integer","title":"Advertised Unreachable Nodes","description":"Observed addresses that were advertised by peers but not reachable on the last check."},"observed_addresses":{"type":"integer","title":"Observed Addresses","description":"Distinct addresses observed during crawls."},"observed_ipv4_addresses":{"type":"integer","title":"Observed Ipv4 Addresses","description":"Distinct observed IPv4 addresses from crawler observations."},"observed_ipv6_addresses":{"type":"integer","title":"Observed Ipv6 Addresses","description":"Distinct observed IPv6 addresses from crawler observations."},"observed_tor_addresses":{"type":"integer","title":"Observed Tor Addresses","description":"Distinct observed Tor/onion addresses from crawler observations."},"observed_unknown_addresses":{"type":"integer","title":"Observed Unknown Addresses","description":"Distinct observed addresses without a known network type."},"advertised_unreachable_ipv4_addresses":{"type":"integer","title":"Advertised Unreachable Ipv4 Addresses","description":"Observed IPv4 addresses advertised by peers but not reachable on the last check."},"advertised_unreachable_ipv6_addresses":{"type":"integer","title":"Advertised Unreachable Ipv6 Addresses","description":"Observed IPv6 addresses advertised by peers but not reachable on the last check."},"advertised_unreachable_tor_addresses":{"type":"integer","title":"Advertised Unreachable Tor Addresses","description":"Observed Tor/onion addresses advertised by peers but not reachable on the last check."},"reachable_ipv4_nodes":{"type":"integer","title":"Reachable Ipv4 Nodes","description":"Reachable observed IPv4 nodes."},"reachable_ipv6_nodes":{"type":"integer","title":"Reachable Ipv6 Nodes","description":"Reachable observed IPv6 nodes."},"reachable_tor_nodes":{"type":"integer","title":"Reachable Tor Nodes","description":"Reachable observed Tor/onion nodes."},"ipv4_nodes":{"type":"integer","title":"Ipv4 Nodes","description":"Backward-compatible alias for reachable_ipv4_nodes."},"ipv6_nodes":{"type":"integer","title":"Ipv6 Nodes","description":"Backward-compatible alias for reachable_ipv6_nodes."},"tor_nodes":{"type":"integer","title":"Tor Nodes","description":"Backward-compatible alias for reachable_tor_nodes."},"last_crawl_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Crawl Time"}},"type":"object","required":["reachable_nodes","advertised_unreachable_nodes","observed_addresses","observed_ipv4_addresses","observed_ipv6_addresses","observed_tor_addresses","observed_unknown_addresses","advertised_unreachable_ipv4_addresses","advertised_unreachable_ipv6_addresses","advertised_unreachable_tor_addresses","reachable_ipv4_nodes","reachable_ipv6_nodes","reachable_tor_nodes","ipv4_nodes","ipv6_nodes","tor_nodes","last_crawl_time"],"title":"StatsResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionBreakdown":{"properties":{"user_agent":{"type":"string","title":"User Agent"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["user_agent","count"],"title":"VersionBreakdown"}}}}