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.

Attach router interface

POST
/scopes/{scopeId}/network/routers/{routerId}/network-interfaces

Attaches a new internal interface to the router (the "Add interface" action and inline draft row on the Interfaces tab of the router detail page). The caller supplies the target subnet, optionally the owning network (defaulted to the subnet's network when omitted) and a fixedIp (auto-assigned from the subnet when omitted). On acceptance the interface appears in the router's Interfaces tab and the subnet's traffic is routed through this router; the interface id is generated by the backend. Validation: router must exist and be visible in scope → 404 NOT_FOUND; subnet is required and must reference an accessible subnet in the scope → 422 VALIDATION_FAILED when missing/blank, 404 when the subnet or network reference is unknown; fixedIp, when supplied, must be a valid address inside the subnet CIDR and not already in use → 422 on malformed/out-of-range, 409 CONFLICT when the address is taken or the subnet is already attached to this router. Async & state: Asynchronous — returns 202 with the RouterInterface in its transitional DOWN state while the port is wired; a resource.updated SSE frame with kind: network.router patches the interface entry to terminal ACTIVE on success, or leaves it DOWN with the failure reported on the parent router activity. Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin rights; 404 unknown router, subnet, or network; 409 subnet already attached to the router or fixed IP already allocated; 422 missing subnet or malformed fixed IP; 500 internal failure. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original 202 response with the same interface id instead of attaching a duplicate port — duplicate creation here would be harmful, so retries are made safe.

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.

routerId*string

Identifier of the router.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Request Body

application/json
  1. body

Payload for attaching an internal interface (Add interface draft row).

subnet*string

Subnet to attach to the router, as its UUID. A subnet name is rejected (422) -- names are not resolved.

network?string

Network (VNet) owning the subnet. Defaults to the subnet's network when omitted.

fixedIp?string

Fixed IP for the router port inside the subnet. Auto-assigned when omitted.

Response Body

Interface attach accepted; the interface is returned in its transitional DOWN state.

application/json
  1. response

Internal interface attaching a subnet to the router.

id*string

Interface identifier.

subnet*string

Subnet attached via this interface.

network*string

Network (VNet) owning the subnet.

fixedIp*string

Fixed IP of the router port inside the subnet.

status*string

Interface operational status.

Value in"ACTIVE""DOWN"
platformManaged?boolean

False when the interface was attached to the router by another service running inside the cloud rather than by this platform — Manila hangs its own service subnet (10.254.0.1) off the tenant router, for example. Such ports are shown deliberately, so the customer can see everything that is on their router, but they are read-only here: only the service that created one can remove it, and a router delete stays blocked while one is attached.

Defaulttrue
curl -X POST "https://example.com/scopes/string/network/routers/string/network-interfaces" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "subnet": "string"  }'
{  "id": "string",  "subnet": "string",  "network": "string",  "fixedIp": "string",  "status": "ACTIVE",  "platformManaged": true}