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 routers

GET
/scopes/{scopeId}/network/routers

Lists Router records in the active tenant/subscription/project scope, powering the Routers page table. This single endpoint serves both the plain route-load listing and the search/filter/sort/pagination controls: q performs a case-insensitive substring match on the router name, status narrows by lifecycle state (the "Active" counter chip), ha narrows to high-availability routers (the "HA" counter chip), and sort/order support the sortable columns (name, createdAt). Each row carries the external gateway (with SNAT flag and external IP), interface count, static-route count, HA/DVR markers, and creation time. Validation: scopeId must resolve to a scope the caller can read, else 403/404 semantics apply; malformed query parameters (unknown status value, non-boolean ha, page/pageSize out of range) → 422 VALIDATION_FAILED. Async & state: Synchronous read; no state change. Results reflect the latest read model including routers still in transitional BUILD state and routers undergoing async deletion. 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. Pagination cursors remain stable across repeated calls with identical parameters.

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 router lifecycle status (the "Active" counter chip filters to ACTIVE).

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

Filter to high-availability routers only (the "HA" counter chip).

Response Body

Paginated collection of routers visible in the active 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/routers"
{  "data": [    {      "origin": "portal",      "id": "string",      "name": "string",      "status": "ACTIVE",      "statusReason": "string",      "statusReasonCode": "string",      "adminStateUp": true,      "ha": true,      "distributed": true,      "externalGateway": {        "externalNetwork": "string",        "externalIp": "string",        "snatEnabled": true      },      "interfaces": [        {          "id": "string",          "subnet": "string",          "network": "string",          "fixedIp": "string",          "status": "ACTIVE",          "platformManaged": true        }      ],      "routes": [        {          "id": "string",          "destination": "string",          "nexthop": "string"        }      ],      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}