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.
Refresh router state
Re-reads the router from the provider and rebuilds its read model (the "Refresh" action in the router detail page):
status, externalGateway, interfaces and routes are overwritten with what Neutron currently reports, and
the refreshed Router is returned. This is the way back for a projection that drifted from the provider — for
example a router whose create failed half-way and was left showing ERROR while Neutron held it ACTIVE.
statusReason is not cleared by a refresh: it explains the last failed command, which a re-read does not undo.
Validation: router must exist and be visible in scope → 404 NOT_FOUND; a router that never reached the
provider (no provider id — still provisioning, or its create was refused) has nothing to refresh from → 409
CONFLICT; a router the provider no longer has is removed from the read model → 404 NOT_FOUND.
Async & state: Synchronous — returns 200 with the refreshed Router read model; no provider configuration is
mutated.
Errors: 401 unauthenticated; 403 caller lacks reader access to the scope; 404 unknown router, or the router
no longer exists in the provider; 409 router has no provider resource; 500 provider read failure.
Idempotency/Concurrency: Safe to repeat; it only reconciles observed state. No Idempotency-Key is required.
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.
State reconciled; the refreshed router read model is returned.
application/json- response
Virtual router connecting subnets and reaching external networks.
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*stringRouter identifier.
name*stringRouter name (lowercase letters, numbers, hyphens; max 63 chars).
status*NetworkStatusLifecycle status shared by networking resources.
"ACTIVE""DOWN""BUILD""ERROR"statusReason*|Human-readable reason the last lifecycle command on this router failed (e.g. the Neutron message of a refused create or gateway attach); null once a later command settles the router healthy, or when nothing failed. Mirrors VirtualNetwork.statusReason. A router whose create failed after the Neutron router already existed shows the provider's real status, gateway, interfaces and routes, with the failure explained here.
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.
adminStateUp*booleanAdministrative state of the router.
ha*booleanHigh availability (active/standby pair) enabled.
distributed*booleanDistributed virtual router (DVR) mode.
externalGateway*|nullExternal gateway attachment, or null when the router is internal-only.
interfaces*array<>Internal interfaces attached to the router.
routes*array<>Static routes configured on the router.
createdAt*stringCreation timestamp (ISO 8601).
date-timecurl -X POST "https://example.com/scopes/string/network/routers/string/actions/refresh"{ "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"}