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.
Add static route
Adds a static route to the router's route table (the "Add route" action and inline draft row on the Static
routes tab of the router detail page, and the optional initial routes section of the router creation form). The caller
supplies a destination CIDR and a nexthop IP; on acceptance the route appears in the Static routes tab
and in the effective Route table in lookup order after connected-subnet routes.
Validation: router must exist and be visible in scope → 404 NOT_FOUND; destination is required and must
be a syntactically valid CIDR (e.g. 10.20.0.0/16) → 422 VALIDATION_FAILED; nexthop is required and must be
a valid IP address reachable via one of the router's attached interfaces → 422 on malformed or unreachable
next hop, and of the same IP version as destination → 422 on nexthop otherwise; a route
with the same destination CIDR must not already exist on this router → 409 CONFLICT.
Async & state: Asynchronous — returns 202 with the accepted StaticRoute (id assigned by the backend);
dataplane route-table programming completes shortly after, signalled by a resource.updated SSE frame with
kind: network.router patching the parent router's routes array. Terminal outcome: route present and
effective, or removed with the failure reported on the router activity feed.
Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin rights; 404 unknown router; 409
duplicate destination CIDR on this router; 422 missing/malformed destination or next hop; 500 internal
failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original 202
response with the same route id instead of inserting a duplicate row — retries are made safe where duplicate
creation would be harmful.
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.
routerId*stringIdentifier of the router.
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 for adding a static route (Add route draft row / create-router routes section).
destination*stringDestination CIDR (e.g. 10.20.0.0/16).
nexthop*stringNext-hop IP address (e.g. 10.0.1.254).
Static route accepted; the route entry is returned while table programming completes.
application/json- response
Manually configured route entry in the router's table.
id*stringRoute identifier.
destination*stringDestination CIDR (e.g. 172.16.0.0/16).
nexthop*stringNext-hop IP address.
curl -X POST "https://example.com/scopes/string/network/routers/string/routes" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "destination": "string", "nexthop": "string" }'{ "id": "string", "destination": "string", "nexthop": "string"}