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.
Create a virtual network
Provisions a new virtual network in the active scope from the network creation form: network
name, address space (CIDR), MTU, share-across-projects flag, optional seed subnets
(name/cidr/gateway rows), optional DNS resolver overrides and cost-allocation tags. The region
is fixed to the active scope's region. On acceptance the network becomes discoverable in the
scoped list, initially in BUILD state.
Validation: name must match ^[a-z0-9-]{1,63}$ else 422 VALIDATION_FAILED; cidr must be
a valid private RFC 1918 CIDR (form 10.0.0.0/16) else 422; mtu must be an integer in
1280–9000 else 422; each seed subnet CIDR must parse and be contained in the address space else
422; CIDR overlap with an existing network in the scope maps to 409 CONFLICT; exceeding the
network quota for the subscription maps to 409 QUOTA_EXCEEDED; unresolvable scope references map
to 404 NOT_FOUND.
Async & state: Asynchronous (202). Returns the full VirtualNetwork resource in its
transitional BUILD state; the backend emits resource.updated SSE frames
(kind: network, patch: {status}) until the terminal state ACTIVE or ERROR is reached.
Errors: 401 unauthenticated; 403 caller is not owner/admin/contributor in the scope;
404 unknown scope; 409 CONFLICT on duplicate name or overlapping CIDR; 409 QUOTA_EXCEEDED when
the network quota is exhausted; 409 CAPACITY_UNAVAILABLE when the region cannot place the
network; 422 on field validation failure; 500 on provisioning-pipeline failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the
original 202 with the same network id instead of provisioning a duplicate.
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.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Payload of the network creation form.
name*string^[a-z0-9-]{1,63}$cidr?|Optional address space CIDR — private RFC 1918 range, e.g. 10.0.0.0/16. Without subnets, this range becomes the network's first subnet ("-subnet", gateway auto-assigned); omit both to create a network with no address space (add subnets later).
mtu?|Link MTU. OMIT to inherit the deployment's configured default (PUBLICCLOUD_DEFAULT_NETWORK_MTU) — the right value is a property of the cloud this environment targets, not of the request. On a nested OpenStack the tenant VXLAN ceiling drops by another 50 bytes per encapsulation layer, so a spec-level constant would be wrong on at least one deployment.
1280 <= value <= 9000shared?booleanShare across projects in the subscription.
falsesubnets?array<>dnsServers?array<string>Resolvers for the network: every subnet created under it — the inline subnets seeds below AND subnets added later through POST .../networks/{networkId}/subnets — is created with these as its dnsNameservers unless that request supplies its own. Omit/empty to leave subnets on the cloud's own default resolvers. There is no resolver setting on a Neutron network itself; this value is applied subnet-by-subnet at subnet-creation time, and a later PATCH of the network's dnsServers rewrites it on every existing subnet.
tags?array<>items <= 50Creation accepted; returns the network in its transitional BUILD state.
application/json- response
Virtual network (VNet) list/detail core record.
origin?stringWhere the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.
"portal""api""system""imported"id*stringname*stringcidr?|Address space CIDR, e.g. 10.0.0.0/16. Null until a subnet defines address space.
status*VirtualNetworkStatusLifecycle status of a virtual network (status-registry kind network).
"ACTIVE""DOWN""BUILD""ERROR"statusReason*|Human-readable reason for the current status when it is a failure (e.g. "Requested MTU is too big, maximum is 1400." on an ERROR network); null while the network is healthy or the failure carried no detail. Mirrors Instance.statusReason / Volume.statusReason: an ERROR row explains itself on the read model instead of forcing the console to go read the tracking Operation.
statusReasonCode*|Machine-readable companion to statusReason: a small, OPEN vocabulary of codes the console can branch on without parsing the human text, deliberately a plain string rather than a closed enum so a code the client does not recognize yet degrades to the generic failure message. Today the only value is cancelled: the resource is in its failure state because its create operation was CANCELLED; a provider object the create had already built may be left in place, and the resource's DELETE removes it. Reported only while the resource is in that failure state; null otherwise.
shared*booleanShared across projects in the subscription.
external*booleanProvider/external network flag.
mtu*integeradminStateUp*booleanavailabilityZone*stringsubnets*array<>tags*array<>User-supplied resource tags applied to the network.
createdAt*stringdate-timeproviderId?|neutron's UUID for this network; null until the worker has created it. An instance NIC's netId is this id.
curl -X POST "https://example.com/scopes/string/network/networks" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "origin": "portal", "id": "string", "name": "string", "cidr": "string", "status": "ACTIVE", "statusReason": "string", "statusReasonCode": "string", "shared": true, "external": true, "mtu": 0, "adminStateUp": true, "availabilityZone": "string", "subnets": [ { "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" } ] } ], "tags": [ { "key": "string", "value": "string" } ], "createdAt": "2019-08-24T14:15:22Z", "providerId": "string"}