Subnet API

Subnet API

Allocate address ranges and query usable capacity and reservation owners.

The Subnet API manages IPv4 or IPv6 ranges within one private network. It reports usable capacity rather than requiring clients to infer infrastructure reservations.

POST/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/subnets
Scope
networks:write
Auth
Bearer API key

Creates an address range within the selected network.

Subnet definition
namestringrequired
Display name.
cidrstringrequired
Canonical IPv4 or IPv6 network prefix with host bits clear.
gateway_addressstringoptional
Optional address permitted by the region's subnet configuration.
defaultRegion-selected address

Returns 202 with subnet ID and operation. Prefix overlap in the routing domain returns 422 overlapping_prefix. Invalid network addresses return 422 invalid_cidr; input is not silently rounded to the containing network. IPv6 creation also requires an approved regional prefix.

Read capacity

GET/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/subnets/{subnet_id}
Scope
networks:read
Auth
Bearer API key

Returns cidr, address_family, gateway_address, reserved_ranges, usable_count, allocated_count, and state. Requires networks:read. Large IPv6 counts are decimal strings so clients do not lose precision through JSON floating-point conversion.

A capacity response returns address counts as decimal strings:

JSON
{
  "data": {
    "id": "sub_production4",
    "cidr": "10.42.0.0/24",
    "address_family": "ipv4",
    "gateway_address": "10.42.0.1",
    "usable_count": "253",
    "allocated_count": "2"
  }
}

The illustrated count assumes only the shown gateway and normal IPv4 boundary reservations; clients must read the actual reservation set for their subnet.

Inspect allocations

GET/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/subnets/{subnet_id}/allocations
Scope
networks:read
Auth
Bearer API key

Returns address, holding resource ID, reservation state, and active operation ID. It supports standard cursor pagination and an exact address filter.

An allocation can remain reserved while its interface operation reconciles. The API does not offer a blind force-release action that could assign an address to two guests. Resolve the owning interface or operation first.

Change or remove

PATCH/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/subnets/{subnet_id}
Scope
networks:write
Auth
Bearer API key

Updates subnet configuration within its dependency constraints.

Requires If-Match and permits name changes. Changing an occupied CIDR returns 409 subnet_in_use. Use another subnet and an explicit readdressing procedure.

DELETE/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/subnets/{subnet_id}
Scope
networks:write
Auth
Bearer API key

Deletes an unused subnet through a removal operation.

Requires no live allocations or gateway dependencies and returns 202 for accepted removal. A retained allocation appears in the conflict response with its owner ID.

Use Interface API to allocate an address and IPv6 networking for address-family behavior.