Networking

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

POST
/scopes/{scopeId}/network/networks/{networkId}/subnets

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

networkId*string

Identifier of the virtual network within the scope.

Header Parameters

Idempotency-Key?string

Optional; 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.

Formatuuid

Request Body

application/json
  1. body

Inline "Add subnet" draft payload (the network detail page subnets tab).

name*string

Subnet name; unique within the network.

Match^[^\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}])?$
Length1 <= length <= 255
cidr*string
gateway?string

Optional 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.

Response Body

Subnet created and returned with its allocated pool and gateway.

application/json
  1. response

Subnet of a virtual network, including its DHCP allocation pool.

id*string
name*string
cidr*string

Subnet CIDR, e.g. 10.0.1.0/24.

ipVersion*integer

IP protocol version of the subnet.

Value in46
gatewayIp*|

Gateway IP of the subnet; null when the gateway is disabled.

dhcpEnabled*boolean
allocationStart*string

First IP of the first DHCP allocation pool (convenience mirror of allocationPools[0].start).

allocationEnd*string

Last 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"    }  ]}