Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Add a subnet to a virtual network
Creates a subnet inside the given virtual network from the inline "Add subnet" draft row in
the network detail page (fields: name, CIDR, optional gateway). The backend allocates the DHCP pool,
derives the gateway when omitted (first usable host), enables DHCP by default, and the subnet
immediately appears in the network's subnet table with its available-IP capacity computed from
the CIDR mask.
Validation: name is required and must be unique within the network else
422 VALIDATION_FAILED / 409 CONFLICT; cidr must parse, be contained within the network's
address space, and not overlap any existing subnet — containment/overlap violations map to
409 CONFLICT, parse failures to 422; gateway when supplied must be an IP inside the subnet
CIDR else 422; unknown networkId maps to 404 NOT_FOUND; exceeding the per-network subnet quota
maps to 409 QUOTA_EXCEEDED.
Async & state: Synchronous (201): subnet allocation is a fast control-plane write and the
full Subnet resource is returned immediately. A resource.updated SSE frame for the parent
network (kind: network, patch: {subnets}) notifies other sessions; no transitional state exists
on the subnet itself.
Errors: 401 unauthenticated; 403 caller lacks contributor rights in the scope; 404 unknown
networkId; 409 CONFLICT on duplicate name or CIDR overlap; 409 QUOTA_EXCEEDED on subnet quota;
422 on malformed name/cidr/gateway; 500 on allocation failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); a replay with the
same key returns the
originally created subnet (same id) instead of allocating a second overlapping range.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
networkId*stringIdentifier of the virtual network within the scope.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
Inline "Add subnet" draft payload (the network detail page subnets tab).
name*stringSubnet name; unique within the network.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255cidr*stringgateway?stringOptional gateway IP inside the subnet CIDR; derived when omitted.
dnsNameservers?array<string>Resolvers handed to instances on this subnet (DHCP option 6). OMIT to inherit the parent network's dnsServers, which is what that field is for; supply it to OVERRIDE the network default for this subnet. An explicit empty array means "no resolvers on this subnet" and also overrides the network default — it is not the same as omitting the field. The override lasts until the next PATCH of the network's dnsServers, which rewrites every subnet.
allocationPools?array<>Optional explicit DHCP allocation pools; omit to let Neutron derive the default pool from the CIDR.
Subnet created and returned with its allocated pool and gateway.
application/json- response
Subnet of a virtual network, including its DHCP allocation pool.
id*stringname*stringcidr*stringSubnet CIDR, e.g. 10.0.1.0/24.
ipVersion*integerIP protocol version of the subnet.
46gatewayIp*|Gateway IP of the subnet; null when the gateway is disabled.
dhcpEnabled*booleanallocationStart*stringFirst IP of the first DHCP allocation pool (convenience mirror of allocationPools[0].start).
allocationEnd*stringLast IP of the first DHCP allocation pool (convenience mirror of allocationPools[0].end).
dnsNameservers*array<string>hostRoutes*array<>Static host routes configured on the subnet (DHCP option 121).
allocationPools*array<>DHCP allocation pools (the address ranges Neutron hands out); empty when the subnet has no pool.
curl -X POST "https://example.com/scopes/string/network/networks/string/subnets" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "cidr": "string" }'{ "id": "string", "name": "string", "cidr": "string", "ipVersion": 4, "gatewayIp": "string", "dhcpEnabled": true, "allocationStart": "string", "allocationEnd": "string", "dnsNameservers": [ "string" ], "hostRoutes": [ { "destination": "string", "nexthop": "string" } ], "allocationPools": [ { "start": "string", "end": "string" } ]}