{ "openapi": "3.1.1", "info": { "title": "ASN Relationship Explorer API", "version": "1.0.0", "summary": "An autonomous system at a glance: holder, country, BGP neighbours and announced prefixes.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://asnrelationshipexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "An autonomous system at a glance: holder, country, BGP neighbours and announced prefixes.", "description": "Explains an Autonomous System Number with RIPEstat data: registered holder and country, neighbours observed in RIPE RIS AS paths (left = towards the collectors, typically upstreams/peers; right = towards the origin, typically customers), announced IPv4/IPv6 prefixes with address-space totals, and a neighbour graph.\n\nMethodology:\n- as-overview: registered holder and whether the AS is announced; rir-stats-country: country of the registration (RIR statistics), not where the network operates.\n- asn-neighbours: ASes adjacent to this AS in RIS AS paths. Per RIPEstat, \"left\" neighbours appear between this AS and the RIS collector (typically its upstream providers or peers) and \"right\" neighbours appear between it and the origin (typically customers). \"Uncertain\" = seen on the left only as direct peers of a RIS collector. \"Power\" = how often the adjacency was observed. Public BGP data cannot reliably separate peers from providers.\n- announced-prefixes: prefixes originated by the AS over RIPEstat's default window (last 2 weeks); totals in /24 (IPv4) and /48 (IPv6) equivalents.\n- Live mode also looks up holder names of the 10 strongest neighbours (as-overview).", "tags": [ "infrastructure" ], "x-mcp-tool": "asn_relationship_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnRelationshipExplorerInput" }, "examples": { "example1": { "summary": "Pasted RIPEstat data for AS3333 (RIPE NCC)", "value": { "mode": "pasted", "maxNeighbours": 25, "pasted": "{\"asn\":\"AS3333\",\"asOverview\":{\"data\":{\"type\":\"as\",\"resource\":\"3333\",\"block\":{\"resource\":\"3154-3353\",\"desc\":\"Assigned by RIPE NCC\",\"name\":\"IANA 16-bit Autonomous System (AS) Numbers Registry\"},\"holder\":\"RIPE-NCC-AS Reseaux IP Europeens Network Coordination Centre (RIPE NCC)\",\"announced\":true}},\"asnNeighbours\":{\"data\":{\"resource\":\"3333\",\"query_endtime\":\"2026-10-14T00:00:00\",\"neighbour_counts\":{\"left\":5,\"right\":1,\"unique\":7,\"uncertain\":1},\"neighbours\":[{\"asn\":1103,\"type\":\"left\",\"power\":14821,\"v4_peers\":81016,\"v6_peers\":7309},{\"asn\":1273,\"type\":\"left\",\"power\":7548,\"v4_peers\":74920,\"v6_peers\":27694},{\"asn\":1136,\"type\":\"left\",\"power\":4442,\"v4_peers\":40372,\"v6_peers\":5525},{\"asn\":12859,\"type\":\"left\",\"power\":2512,\"v4_peers\":17420,\"v6_peers\":1059},{\"asn\":8218,\"type\":\"uncertain\",\"power\":40,\"v4_peers\":300,\"v6_peers\":10},{\"asn\":14840,\"type\":\"left\",\"power\":2,\"v4_peers\":30,\"v6_peers\":0},{\"asn\":197000,\"type\":\"right\",\"power\":120,\"v4_peers\":900,\"v6_peers\":700}]}},\"announcedPrefixes\":{\"data\":{\"resource\":\"3333\",\"query_starttime\":\"2026-09-30T08:00:00\",\"query_endtime\":\"2026-10-14T08:00:00\",\"prefixes\":[{\"prefix\":\"2a13:27c0::/44\",\"timelines\":[{\"starttime\":\"2026-09-30T08:00:00\",\"endtime\":\"2026-10-07T00:00:00\"},{\"starttime\":\"2026-10-07T16:00:00\",\"endtime\":\"2026-10-14T08:00:00\"}]},{\"prefix\":\"193.0.18.0/23\",\"timelines\":[{\"starttime\":\"2026-09-30T08:00:00\",\"endtime\":\"2026-10-14T08:00:00\"}]},{\"prefix\":\"193.0.22.0/23\",\"timelines\":[{\"starttime\":\"2026-09-30T08:00:00\",\"endtime\":\"2026-10-14T08:00:00\"}]},{\"prefix\":\"193.0.0.0/21\",\"timelines\":[{\"starttime\":\"2026-09-30T08:00:00\",\"endtime\":\"2026-10-14T08:00:00\"}]},{\"prefix\":\"2001:67c:2e8::/48\",\"timelines\":[{\"starttime\":\"2026-09-30T08:00:00\",\"endtime\":\"2026-10-14T08:00:00\"}]}]}},\"rirStatsCountry\":{\"data\":{\"located_resources\":[{\"resource\":\"3333\",\"location\":\"NL\"}]}}}" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnRelationshipExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "AsnRelationshipExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Mode", "type": "string", "enum": [ "live", "pasted" ], "default": "live" }, "asn": { "title": "AS number", "type": "string", "maxLength": 14 }, "maxNeighbours": { "title": "Neighbours in the graph", "type": "integer", "minimum": 1, "maximum": 55, "default": 25 }, "pasted": { "title": "RIPEstat responses (JSON)", "description": "Pasted mode: {asn, asOverview, asnNeighbours?, announcedPrefixes?, rirStatsCountry?} — full RIPEstat responses or their \"data\" objects.", "type": "string", "maxLength": 200000 } }, "required": [] }, "AsnRelationshipExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "asn", "holder", "country", "announced", "block", "neighbourCounts", "neighbours", "prefixCounts", "prefixes", "queryTime", "prefixWindow", "findings" ], "properties": { "asn": { "type": "integer" }, "holder": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "announced": { "type": "boolean" }, "block": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "resource", "description" ], "properties": { "resource": { "type": "string" }, "description": { "type": "string" } } }, "neighbourCounts": { "type": "object", "additionalProperties": false, "required": [ "left", "right", "uncertain", "unique" ], "properties": { "left": { "type": "integer" }, "right": { "type": "integer" }, "uncertain": { "type": "integer" }, "unique": { "type": "integer" } } }, "neighbours": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "asn", "type", "power", "v4Peers", "v6Peers", "holder" ], "properties": { "asn": { "type": "integer" }, "type": { "type": "string", "enum": [ "left", "right", "uncertain" ] }, "power": { "type": "integer" }, "v4Peers": { "type": [ "integer", "null" ] }, "v6Peers": { "type": [ "integer", "null" ] }, "holder": { "type": [ "string", "null" ] } } } }, "prefixCounts": { "type": "object", "additionalProperties": false, "required": [ "ipv4", "ipv6", "ipv4Slash24Equivalents", "ipv6Slash48Equivalents" ], "properties": { "ipv4": { "type": "integer" }, "ipv6": { "type": "integer" }, "ipv4Slash24Equivalents": { "type": "integer" }, "ipv6Slash48Equivalents": { "type": "integer" } } }, "prefixes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "prefix", "family", "firstSeen", "lastSeen", "periods" ], "properties": { "prefix": { "type": "string" }, "family": { "type": "string", "enum": [ "IPv4", "IPv6" ] }, "firstSeen": { "type": [ "string", "null" ] }, "lastSeen": { "type": [ "string", "null" ] }, "periods": { "type": "integer" } } } }, "queryTime": { "type": [ "string", "null" ] }, "prefixWindow": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "start", "end" ], "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "severity", "area", "finding" ], "properties": { "severity": { "type": "string", "enum": [ "high", "medium", "low", "info" ] }, "area": { "type": "string" }, "finding": { "type": "string" } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }