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.
Update virtual network configuration
Applies a partial update to the selected network's mutable configuration. Backs three UI
gestures in the network detail page: "Save DNS server" (replace the dnsServers list), "Edit address
space" (change cidr), and the generic Edit affordance for name, MTU, shared flag and admin
state. Only fields present in the body are changed; the updated detail read model is returned
so the view can refresh in place.
Validation: each present field is validated — cidr must be a valid RFC 1918 CIDR that
still contains every existing subnet, else 422 VALIDATION_FAILED; shrinking the address space
below allocated subnets maps to 409 CONFLICT; mtu must be 1280–9000 else 422; each entry in
dnsServers must be a valid IP literal else 422; name must match ^[a-z0-9-]{1,63}$ else
422; unknown networkId maps to 404 NOT_FOUND.
Async & state: Synchronous (200) for name/DNS/tag/admin-state changes. An address-space
change that requires dataplane reconfiguration is accepted with 202 and the network re-enters
BUILD until ACTIVE/ERROR; resource.updated SSE frames (kind: network, patch:
{status, cidr}) track the transition.
Errors: 401 unauthenticated; 403 caller lacks contributor rights; 404 unknown networkId;
409 CONFLICT when the new CIDR overlaps a peered network or orphans existing subnets;
412 PRECONDITION_FAILED on stale If-Match; 422 on field validation failure; 500 on apply failure.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. A repeated identical PATCH re-applies the same fields (same end
state) and bumps the ETag, so resending a request that already succeeded with its original
If-Match gets 412. If-Match with the ETag from the detail read is honored — a mismatch returns
412 and leaves the resource untouched.
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.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Partial update of a network — name, address space, MTU, shared flag, admin state, DNS servers, tags. Only present fields are changed.
name?string^[a-z0-9-]{1,63}$cidr?stringNew address space CIDR ("Edit address space"); must still contain all existing subnets.
mtu?integer1280 <= value <= 9000shared?booleanadminStateUp?booleandnsServers?array<string>Full replacement resolver list ("Save DNS server" / remove server). RETROACTIVE: this rewrites dnsNameservers on EVERY subnet of the network that already exists — including a subnet whose resolvers were overridden at create time or by a later subnet PATCH, whose override is discarded — and it becomes the default that subnets created afterwards inherit. So the network-level list is "the resolvers of this network", not a historical default. To give one subnet different resolvers, patch that subnet (PATCH .../networks/{networkId}/subnets/{subnetId}) AFTER the network-level change, not before.
tags?array<>items <= 50Update applied synchronously; returns the refreshed detail read model.
application/json- response
Full network detail read model — the core record plus the resolved DNS servers and address-usage counters.
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.
dnsServers*array<string>The network's resolver list — what a subnet created under it inherits as its dnsNameservers when the create request does not supply its own, and what a PATCH of this field writes onto every existing subnet. It is not a live rollup, so it can differ from an individual subnet: a subnet created with an explicit dnsNameservers, or patched afterwards, keeps its own list until the next network-level PATCH overwrites it. Read subnets[].dnsNameservers for what instances on a given subnet actually receive.
totalAddresses*integerTotal usable host capacity across allocation pools.
usedAddresses*integercurl -X PATCH "https://example.com/scopes/string/network/networks/string" \ -H "Content-Type: application/json" \ -d '{}'{ "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", "dnsServers": [ "string" ], "totalAddresses": 0, "usedAddresses": 0}