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.

List network interfaces (ports) in the active scope

GET
/scopes/{scopeId}/network/network-interfaces

Returns the Network Interface (port) collection for the active tenant/subscription/project scope, exactly as rendered by the Interfaces page on route load. This single operation also serves the search/filter/sort/paginate behavior (canonical id network.network_interface.search_filter_sort collapses here): the free-text q is a case-insensitive substring match over name, fixed IP, MAC, network name, subnet name and attached-device name; the UI quick-filter chips map to attachment=attached|unattached (device bound or not) and portSecurity=false ("Port security off"); status narrows to a port lifecycle state. Sortable columns are name, network, ip, sgs (security-group count) and created. Each row carries the stable identifiers and state the table needs (id, name, network/subnet, fixed IP, MAC, security-group ids, status pill, floating IP, device, createdAt). Read-model only — never mutates the resource. Validation: scopeId must resolve to a scope the caller can read; page/pageSize must be positive integers; unknown sort column, bad order, an attachment value outside attached|unattached, a non-boolean portSecurity, or a status outside the declared enum → ERR_VALIDATION (422). Async & state: Synchronous read; no state change. Errors: 401 when the session is missing/expired; 403 when the caller lacks reader access to the scope; 422 on malformed query parameters; 500 on backend read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
status?string

Filter by port lifecycle status.

Value in"active""down""build"
attachment?string

UI quick-filter — only ports with a bound device ("Attached") or without one ("Unattached").

Value in"attached""unattached"
portSecurity?boolean

Filter by port-security flag; the UI chip "Port security off" sends portSecurity=false.

Response Body

Paginated collection of Network Interfaces visible in the active scope.

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

curl -X GET "https://example.com/scopes/string/network/network-interfaces"
{  "data": [    {      "origin": "portal",      "id": "string",      "name": "string",      "description": "string",      "arn": "string",      "networkId": "string",      "networkName": "string",      "networkExternal": true,      "subnetName": "string",      "subnetCidr": "string",      "fixedIp": "string",      "fixedIps": [        {          "ipAddress": "string",          "subnetId": "string"        }      ],      "mac": "string",      "status": "active",      "statusReason": "string",      "adminStateUp": true,      "portSecurity": true,      "securityGroups": [        "string"      ],      "floatingIp": "string",      "device": {        "kind": "instance",        "id": "string",        "name": "string",        "owner": "string"      },      "bindingType": "normal",      "bindingHost": "string",      "mtu": 0,      "dnsName": "string",      "allowedAddressPairs": [        {          "ip": "string",          "mac": ""        }      ],      "region": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "rxMbps": 0,      "txMbps": 0,      "pps": 0    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}