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
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.
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 attaching an internal interface (Add interface draft row).
subnet*stringSubnet to attach to the router, as its UUID. A subnet name is rejected (422) -- names are not resolved.
network?stringNetwork (VNet) owning the subnet. Defaults to the subnet's network when omitted.
fixedIp?stringFixed IP for the router port inside the subnet. Auto-assigned when omitted.
Interface attach accepted; the interface is returned in its transitional DOWN state.
application/json- response
Internal interface attaching a subnet to the router.
id*stringInterface identifier.
subnet*stringSubnet attached via this interface.
network*stringNetwork (VNet) owning the subnet.
fixedIp*stringFixed IP of the router port inside the subnet.
status*stringInterface operational status.
"ACTIVE""DOWN"platformManaged?booleanFalse 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.
truecurl -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}