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.

Add a security rule to a group

POST
/scopes/{scopeId}/network/security-groups/{securityGroupId}/security-rules

Adds a single rule to an existing security group via the detail view's "Add rule" dialog (available from the header and the inbound/outbound tab "Add" buttons). The dialog offers preset chips (SSH, HTTP, HTTPS, MySQL, PostgreSQL, RDP, DNS, Custom) that pre-fill the fields client-side; the submitted payload is always the concrete rule: direction (Inbound/Outbound), ether type (IPv4/IPv6), protocol (tcp/udp/icmp/any), port range (Port from / Port to — disabled and null for icmp/any), source/dest CIDR or a remote security-group reference, and an optional description. Once applied, the rule is enforced on every port attached to the group. Validation: the parent security group must exist in the scope and not be DELETING → 404 NOT_FOUND / 409 CONFLICT; direction, etherType and protocol must be valid enum values → 422 VALIDATION_FAILED; for tcp/udp, portMin and portMax must be integers 1-65535 with portMin <= portMax → 422; for icmp/any, portMin/portMax must be null → 422; exactly one of remoteCidr (valid CIDR, family matching etherType) or remoteGroup (an accessible security group in the scope) must be set → 422; an identical rule already present or the rules-per-group quota exhausted → 409. Async & state: Asynchronous — returns 202 with an Operation handle; the rule is persisted immediately and propagated to attached ports in the background. resource.updated SSE frames are emitted for the parent security-group resource with a rules-array patch (new rule appended) plus operation.updated frames until propagation reaches the terminal applied state. Errors: 401 unauthenticated; 403 caller lacks contributor rights; 404 unknown parent group; 409 QUOTA_EXCEEDED when the rules-per-group quota is exhausted (identical duplicate rule → 409 CONFLICT); 422 on any field validation failure; 500 on propagation workflow errors. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original 202 Operation without inserting a duplicate rule.

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.

securityGroupId*string

Identifier of the security group receiving the rule.

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 of the "Add security group rule" dialog. Exactly one of remoteCidr or remoteGroup must be set.

direction*string

Traffic direction (Inbound = ingress, Outbound = egress).

Value in"ingress""egress"
etherType*string

Address family the rule matches.

Value in"IPv4""IPv6"
protocol*string

L4 protocol; ports must be null for icmp/any.

Value in"tcp""udp""icmp""any"
portMin?|

"Port from" — start of the port range (1-65535); null for icmp/any, or null together with portMax for a tcp/udp all-ports rule.

portMax?|

"Port to" — end of the port range (1-65535, >= portMin); null for icmp/any, or null together with portMin for a tcp/udp all-ports rule.

remoteCidr?|

Source / dest CIDR the rule matches; null when remoteGroup is used.

remoteGroup?|

Peer security group reference matched instead of a CIDR; null when remoteCidr is used.

description?string

Optional human-readable purpose of the rule.

Lengthlength <= 255

Response Body

Rule accepted; it is being propagated to all attached ports. Track via the returned operation and the parent group's resource.updated frames.

application/json
  1. response

A long-running operation record. GET /operations/{operationId} returns its current state.

id*string

Operation identifier, unique platform-wide.

action*string

Canonical action id that started this operation, e.g. compute.instance.create.

state*OperationState

State machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.

Value in"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"
resourceKind?|

Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.

resourceId?|

Identifier of the target resource; null until the resource is allocated.

resourceName?|

Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).

principalId?|

Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.

sourceIp?|

Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).

progressPercent?|

Best-effort progress; null when the action does not report progress.

Range0 <= value <= 100
error?|null

Populated only when state is FAILED (or CANCELLED with partial rollback notes).

warning?|null

Non-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.

startedAt?|

When the worker began executing; null while PENDING.

finishedAt?|

When a terminal state was reached; null while transitional.

createdAt*string
updatedAt*string
curl -X POST "https://example.com/scopes/string/network/security-groups/string/security-rules" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "direction": "ingress",    "etherType": "IPv4",    "protocol": "tcp"  }'
{  "id": "string",  "action": "string",  "state": "PENDING",  "resourceKind": "string",  "resourceId": "string",  "resourceName": "string",  "principalId": "string",  "sourceIp": "string",  "progressPercent": 0,  "error": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "warning": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "startedAt": "string",  "finishedAt": "string",  "createdAt": "string",  "updatedAt": "string"}