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.

List virtual networks in the active scope

GET
/scopes/{scopeId}/network/networks

Returns the paginated collection of virtual networks (VNets) visible in the active tenant/subscription/project scope, exactly as consumed by the Networks page on route load. Each row carries the stable identifiers, status, CIDR, MTU, shared/external flags and embedded subnets/ports the table needs. This single endpoint also serves the search/filter/sort/paginate behavior (canonical action network.network.search_filter_sort): free-text q matches name or CIDR, the status filter maps the "Active"/"Building" quick chips, and shared=true maps the "Shared" chip; sort/order cover the sortable Name and Created columns. Validation: scopeId must resolve to a tenant/subscription/project the caller can read, else 403 FORBIDDEN; malformed pagination/filter values (unknown status, non-boolean shared, page<1) map to 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. Rows in BUILD will transition to ACTIVE/ERROR via resource.updated SSE frames the client may merge. Errors: 401 when unauthenticated; 403 when the caller lacks reader access to the scope; 422 on malformed query parameters; 500 on backend read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
status?string

Filter by network lifecycle status (quick chips "Active" / "Building" in the Networks page).

Value in"ACTIVE""DOWN""BUILD""ERROR"
shared?boolean

When true, return only networks shared across projects (quick chip "Shared").

Response Body

Paginated list of virtual networks in the scope.

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

curl -X GET "https://example.com/scopes/string/network/networks"
{  "data": [    {      "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"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}