Route API
Create and withdraw revisioned forwarding entries and inspect effective route state.
The Route API manages explicit forwarding entries for a project network. Connected and peering-derived routes are read through the effective view and cannot be overwritten as static entries.
/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/routesCreates a static forwarding entry for the selected network.
destination_cidrstringrequiredgateway_idstringrequiredpriorityintegeroptional100rule1–65535 inclusivedescriptionstringoptionalEmptyReturns 202 with route ID and realization operation. An incompatible address
family or unreachable gateway returns 422 invalid_next_hop. A conflicting
static entry returns 409 route_conflict rather than creating unsupported
equal-cost multipath behavior.
Effective forwarding
/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/effective-routesReturns each prefix, origin, next hop, priority, desired revision, and applied locations. Requires networks:read. The origin value is connected, peering, static, or
private_connection. A private-connection entry also identifies the attachment
and whether its approved prefix came from static configuration or BGP exchange.
A failed gateway does not remove the desired route automatically. Health shows that its configured path is unavailable. Clients must not interpret the continued presence of the route as proof of working forwarding.
Replace a next hop
/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/routes/{route_id}Updates a static route's next hop, priority, or description.
Accepts gateway_id, priority, and description.
It requires If-Match; omitted fields stay unchanged and null is rejected.
Changing the prefix requires creating a reviewed replacement route.
Accepted changes return 202. Applied revisions can differ across an unreachable
set of nodes. The operation identifies those pending locations. Route mutation
does not change guest routes manually configured inside an operating system.
Withdraw
/organizations/{organization_id}/projects/{project_id}/networks/{network_id}/routes/{route_id}Withdraws a static route through a realization operation.
Requires the current ETag and returns 202.
Dependent policy references can return 409 route_in_use. Removing a default
route can break package installation, backup paths, and external API calls even
when private application health remains green.
Verify return routing when switching gateways. Existing connection-tracking state can outlive one route revision or fail under asymmetric paths. See route tables and egress gateways for traffic behavior.