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
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.
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.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter by router lifecycle status (the "Active" counter chip filters to ACTIVE).
"ACTIVE""DOWN""BUILD""ERROR"ha?booleanFilter to high-availability routers only (the "HA" counter chip).
Paginated collection of routers visible in the active scope.
application/json- 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 }}