REST API¶
The calculator exposes a versioned JSON REST API at /api/v1/.
Full machine-readable spec: api/openapi.yaml (OpenAPI 3.1). All 200 responses include a concrete example: block showing a typical response payload.
Authentication¶
All endpoints are unauthenticated by default. Optional Bearer-token authentication and per-token rate limiting can be configured — see Operator Config.
Response format¶
All responses are JSON objects with an ok boolean:
Endpoints¶
GET /api/v1/meta¶
Returns the application version and a list of available endpoints.
GET /api/v1/changelog¶
Returns the full CHANGELOG.md content as a string.
Response:
POST /api/v1/ipv4¶
Calculate IPv4 subnet details.
curl -X POST https://example.com/subnet-calculator/api/v1/ipv4 \
-H 'Content-Type: application/json' \
-d '{"ip":"192.168.1.0","mask":"/24"}'
POST /api/v1/ipv6¶
Calculate IPv6 subnet details.
curl -X POST https://example.com/subnet-calculator/api/v1/ipv6 \
-H 'Content-Type: application/json' \
-d '{"ip":"2001:db8::/32"}'
POST /api/v1/vlsm¶
VLSM planner — allocate variable-length subnets from a parent block.
curl -X POST https://example.com/subnet-calculator/api/v1/vlsm \
-H 'Content-Type: application/json' \
-d '{"network":"10.0.0.0","cidr":24,"subnets":[{"name":"LAN","hosts":50}]}'
POST /api/v1/overlap¶
Two-CIDR overlap check.
curl -X POST https://example.com/subnet-calculator/api/v1/overlap \
-H 'Content-Type: application/json' \
-d '{"cidr_a":"10.0.0.0/24","cidr_b":"10.0.0.128/25"}'
POST /api/v1/split/ipv4¶
Split an IPv4 network into equal-sized sub-networks.
curl -X POST https://example.com/subnet-calculator/api/v1/split/ipv4 \
-H 'Content-Type: application/json' \
-d '{"cidr":"10.0.0.0/24","prefix":26}'
POST /api/v1/split/ipv6¶
Split an IPv6 network into equal-sized sub-networks.
curl -X POST https://example.com/subnet-calculator/api/v1/split/ipv6 \
-H 'Content-Type: application/json' \
-d '{"cidr":"2001:db8::/48","prefix":64}'
POST /api/v1/supernet¶
Find a supernet or summarise routes.
curl -X POST https://example.com/subnet-calculator/api/v1/supernet \
-H 'Content-Type: application/json' \
-d '{"cidrs":["10.0.0.0/25","10.0.0.128/25"],"action":"find"}'
action is "find" (tightest enclosing supernet) or "summarise" (minimal covering set).
POST /api/v1/ula¶
Generate a ULA prefix (RFC 4193).
curl -X POST https://example.com/subnet-calculator/api/v1/ula \
-H 'Content-Type: application/json' \
-d '{"global_id":"aabbccddee"}'
Omit global_id for a randomly generated prefix.
POST /api/v1/rdns¶
Reverse DNS zone for a CIDR.
curl -X POST https://example.com/subnet-calculator/api/v1/rdns \
-H 'Content-Type: application/json' \
-d '{"cidr":"192.168.1.0/24"}'
POST /api/v1/range/ipv4¶
Convert an IP range to a minimal list of CIDR blocks.
curl -X POST https://example.com/subnet-calculator/api/v1/range/ipv4 \
-H 'Content-Type: application/json' \
-d '{"start":"10.0.0.0","end":"10.0.0.255"}'
Response: {"ok":true,"data":{"cidrs":["10.0.0.0/24"]}}
POST /api/v1/tree¶
Build a subnet allocation tree with gap detection.
curl -X POST https://example.com/subnet-calculator/api/v1/tree \
-H 'Content-Type: application/json' \
-d '{"parent":"10.0.0.0/24","children":["10.0.0.0/25","10.0.0.128/25"]}'
POST /api/v1/bulk¶
Run multiple operations in a single request (up to 20).
curl -X POST https://example.com/subnet-calculator/api/v1/bulk \
-H 'Content-Type: application/json' \
-d '{"requests":[{"method":"POST","path":"/ipv4","body":{"ip":"10.0.0.0/8"}}]}'
GET /api/v1/sessions/:id¶
Retrieve a saved VLSM session by ID. Only available when $session_enabled = true in config.php.
Rate limiting¶
When $api_rate_limit_rpm is set (default 60), requests exceeding the limit receive a 429 response with a Retry-After: 60 header. Per-token overrides are supported via $api_rate_limit_tokens.
Endpoint allowlisting¶
Set $api_allowed_endpoints in config.php to restrict which endpoints are accessible. Unlisted endpoints return 404. Example: