{ "openapi": "3.1.1", "info": { "title": "Signalhouse Subnet Planner (VLSM, CIDR aggregation, IPv4/IPv6) API", "version": "1.0.0", "summary": "Subnet calculator, VLSM planner, CIDR aggregation and exclusion for IPv4 and IPv6.", "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://signalhousesubnetplanner.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Subnet calculator, VLSM planner, CIDR aggregation and exclusion for IPv4 and IPv6.", "description": "Plans address space the way network engineers do it: details of any address or prefix (network, usable range, broadcast, RFC 5952 canonical IPv6 form, special-purpose range), equal splits by subnet count or hosts, VLSM allocation for a list of host requirements, aggregation of prefix lists into the minimal CIDR set and a summary route (RFC 4632), a block minus excluded prefixes, and address ranges as CIDR blocks. It is the planner of the Signalhouse Network lab.\n\nMethodology:\n- Addresses are parsed per RFC 791 (dotted decimal without leading zeros) and RFC 4291 (IPv6 with “::” and an optional dotted IPv4 tail); IPv6 is printed in the RFC 5952 canonical form. All arithmetic uses 128-bit integers, so IPv4 and IPv6 follow the same rules.\n- Usable IPv4 hosts exclude the network and broadcast address, except /31 point-to-point links (RFC 3021) and /32 host routes. IPv6 has no broadcast; every address of the prefix is counted.\n- VLSM gives each requirement the smallest aligned power-of-two block that holds its hosts and places it at the first free aligned position (first fit). Sorted largest first, a plan never leaves gaps: if the total fits, every subnet fits. In listed order it reproduces the delegation sequence of RFC 4632 section 6.1, holes included.\n- Aggregation merges overlapping and adjacent prefixes and writes each merged range as the minimal list of aligned CIDR blocks; exclusion and range conversion use the same range-to-CIDR step. The summary route is the longest prefix that covers every input; addresses it covers beyond the inputs need a discard route (RFC 4632 rule 2).\n- The address type comes from the IANA special-purpose registries (RFC 6890 with RFC 1918, 6598, 5737, 3849, 4193, 9637 and others): the most specific matching range wins.", "tags": [ "apps" ], "x-mcp-tool": "signalhouse_subnet_planner", "x-owner-app": "signalhouse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalhouseSubnetPlannerInput" }, "examples": { "example1": { "summary": "Classic VLSM: 192.168.1.0/24 for 100, 50, 25 and 10 hosts plus two router links", "value": { "mode": "vlsm", "block": "192.168.1.0/24", "requirements": [ { "name": "LAN A", "hosts": 100 }, { "name": "LAN B", "hosts": 50 }, { "name": "LAN C", "hosts": 25 }, { "name": "LAN D", "hosts": 10 }, { "name": "Link 1", "hosts": 2 }, { "name": "Link 2", "hosts": 2 } ] } }, "example2": { "summary": "RFC 4632 section 6.1: aggregate the six customer blocks C1–C6", "value": { "mode": "aggregate", "prefixes": "10.24.0.0/21\n10.24.16.0/20\n10.24.8.0/22\n10.24.12.0/22\n10.24.32.0/23\n10.24.34.0/23" } }, "example3": { "summary": "RFC 4632 section 6.1: delegate C1–C6 from 10.24.0.0/13 in arrival order", "value": { "mode": "vlsm", "block": "10.24.0.0/13", "order": "listed", "requirements": [ { "name": "C1", "length": 21 }, { "name": "C2", "length": 20 }, { "name": "C3", "length": 22 }, { "name": "C4", "length": 22 }, { "name": "C5", "length": 23 }, { "name": "C6", "length": 23 } ] } }, "example4": { "summary": "Exclude 10.1.0.0/16 from 10.0.0.0/8", "value": { "mode": "exclude", "block": "10.0.0.0/8", "prefixes": "10.1.0.0/16" } }, "example5": { "summary": "IPv6 details: 2001:0db8:0000:0000:0000:ff00:0042:8329/64", "value": { "mode": "info", "block": "2001:0db8:0000:0000:0000:ff00:0042:8329/64" } }, "example6": { "summary": "Split 2001:db8:abcd::/48 into 4 site prefixes", "value": { "mode": "split", "block": "2001:db8:abcd::/48", "splitBy": "count", "count": 4 } }, "example7": { "summary": "Address range 192.168.0.10 – 192.168.0.200 as CIDR blocks", "value": { "mode": "range", "block": "192.168.0.10 - 192.168.0.200" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalhouseSubnetPlannerResult" } } } }, "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" } } } } } }, "SignalhouseSubnetPlannerInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "What to calculate", "type": "string", "enum": [ "info", "split", "vlsm", "aggregate", "exclude", "range" ], "default": "vlsm" }, "block": { "title": "Block, address or range", "description": "The address block to plan in (VLSM, split, exclude), any address or prefix (details) or a range “first - last” (range mode). Not used for aggregation.", "type": "string", "maxLength": 120, "default": "192.168.1.0/24" }, "requirements": { "title": "Subnets needed (VLSM)", "description": "One row per subnet: a name and the number of hosts it must hold, or a fixed prefix length.", "type": "array", "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Name", "type": "string", "maxLength": 60 }, "hosts": { "title": "Hosts", "type": "integer", "minimum": 1 }, "length": { "title": "Fixed prefix length", "type": "integer", "minimum": 0, "maximum": 128 } }, "required": [] }, "default": [ { "name": "Office LAN", "hosts": 100 }, { "name": "Lab", "hosts": 50 }, { "name": "Wi-Fi guests", "hosts": 25 }, { "name": "Servers", "hosts": 10 }, { "name": "Link to branch", "hosts": 2 } ] }, "order": { "title": "VLSM order", "type": "string", "enum": [ "largest", "listed" ], "default": "largest" }, "allow31": { "title": "Use /31 (IPv4) or /127 (IPv6) for 2-host point-to-point links", "type": "boolean", "default": false }, "ipv6Lan64": { "title": "IPv6: never smaller than a /64 (SLAAC)", "type": "boolean", "default": true }, "splitBy": { "title": "Split by", "type": "string", "enum": [ "count", "hosts", "length" ], "default": "count" }, "count": { "title": "Number of subnets", "type": "integer", "minimum": 1, "maximum": 16777216, "default": 4 }, "hosts": { "title": "Hosts per subnet", "type": "integer", "minimum": 1 }, "newLength": { "title": "New prefix length", "type": "integer", "minimum": 0, "maximum": 128 }, "prefixes": { "title": "Prefixes (one per line)", "description": "Aggregate: the prefixes to summarise. Exclude: the prefixes to cut out of the block. VLSM: prefixes to keep free (reserved).", "type": "string", "maxLength": 60000 } }, "required": [] }, "SignalhouseSubnetPlannerResult": { "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": [ "mode", "family", "block", "info", "rows", "totalSubnets", "free", "unallocated", "aggregated", "summary", "summaryExtraAddresses", "inputCount", "addressesCovered", "utilisationPercent", "notes" ], "properties": { "mode": { "enum": [ "info", "split", "vlsm", "aggregate", "exclude", "range" ] }, "family": { "enum": [ "IPv4", "IPv6", "mixed" ] }, "block": { "type": [ "string", "null" ] }, "info": { "type": [ "object", "null" ], "description": "Details of one address or prefix (mode info): network, netmask, wildcard, broadcast, usable range, counts, special-purpose type with its RFC, reverse DNS name, binary form." }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "prefix", "network", "firstUsable", "lastUsable", "broadcast", "netmask", "addresses", "usable", "hosts", "spare" ], "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "network": { "type": "string" }, "firstUsable": { "type": "string" }, "lastUsable": { "type": "string" }, "broadcast": { "type": [ "string", "null" ] }, "netmask": { "type": "string" }, "addresses": { "type": [ "number", "string" ] }, "usable": { "type": [ "number", "string" ] }, "hosts": { "type": [ "number", "null" ] }, "spare": { "type": [ "number", "string", "null" ] } } }, "description": "Subnets, allocations or CIDR blocks (at most 1024 listed)." }, "totalSubnets": { "type": [ "number", "string" ] }, "free": { "type": "array", "items": { "type": "string" }, "description": "Unused blocks of the plan as a minimal CIDR set." }, "unallocated": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "hosts", "length", "reason" ], "properties": { "name": { "type": "string" }, "hosts": { "type": [ "number", "null" ] }, "length": { "type": "number" }, "reason": { "type": "string" } } } }, "aggregated": { "type": "array", "items": { "type": "string" }, "description": "Minimal prefix list (aggregate, exclude, range)." }, "summary": { "type": [ "string", "null" ], "description": "Single summary route covering every input prefix (aggregate)." }, "summaryExtraAddresses": { "type": [ "number", "string", "null" ], "description": "Addresses inside the summary route that no input prefix covers." }, "inputCount": { "type": "number" }, "addressesCovered": { "type": [ "number", "string", "null" ] }, "utilisationPercent": { "type": [ "number", "null" ] }, "notes": { "type": "array", "items": { "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" } } } } } } } }