Operation details
GET /v1/stream-groups
List layer-four forwarding groups
- operationId
listStreamGroups- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.read
Description (from the contract)
Tenant principals see only groups owned by their current user and tenant. Platform principals can list tenant groups after streams.read authorization.
Parameters
listStreamGroups Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
search | query | string | No | — |
|---|
Responses
listStreamGroups Responses| Status | Description |
|---|
200 | Stable page ordered newest first; stream_count counts live member rules. Fields：items: array<StreamGroup> total: integer(int64) page: integer limit: integer |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/stream-groups
Create a layer-four forwarding group
- operationId
createStreamGroup- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.manage
Description (from the contract)
Tenant principals are fixed to their current scope and user. Platform principals must provide target_scope_id and owner_id. Group membership alone never advances the edge configuration revision.
Parameters
createStreamGroup Parameters| Name | In | Type | Required | Description |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | Yes | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
Request body
application/json · Required：Yes
createStreamGroup Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
remark | string | No | — |
|---|
target_scope_id | string(uuid) | No | Required for platform principals; tenant principals may omit it or use their current scope. |
|---|
owner_id | string(uuid) | No | Required for platform principals; tenant principals may omit it or use their current user. |
|---|
Responses
createStreamGroup Responses| Status | Description |
|---|
201 | Group committed, or an exact idempotent replay returned. Fields：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null name: string remark: string stream_count: integer(int64) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
415 | Exactly one Content-Type field parsing as application/json is required. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
PATCH /v1/stream-groups/{id}
Rename a layer-four forwarding group
- operationId
updateStreamGroup- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.manage
Parameters
updateStreamGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | Exact forward group identity. |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | Yes | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
If-Match | header | string | Yes | Quoted positive current resource revision. |
|---|
Request body
application/json · Required：Yes
updateStreamGroup Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
remark | string | No | — |
|---|
expected_revision | integer(int64) | Yes | Must exactly equal the quoted If-Match revision. |
|---|
Responses
updateStreamGroup Responses| Status | Description |
|---|
200 | Group updated, or an exact idempotent replay returned. Fields：id: string(uuid) display_id: string scope_id: string(uuid) owner: StreamOwner | null name: string remark: string stream_count: integer(int64) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
404 | No visible stream matches the exact immutable stream identity. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
415 | Exactly one Content-Type field parsing as application/json is required. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
DELETE /v1/stream-groups/{id}
Delete an unreferenced layer-four forwarding group
- operationId
deleteStreamGroup- Auth
- API key: header Authorization: CdncaKey <key_id>.<secret>. Effective permissions are the key scopes intersected with the owner’s current permissions.
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：streams.manage
Parameters
deleteStreamGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | Exact forward group identity. |
|---|
X-Request-ID | header | string | No | Caller-stable request identity; invalid or absent values are replaced by middleware. |
|---|
Idempotency-Key | header | string | Yes | Reuse is accepted only for the exact same actor, operation, and normalized input. |
|---|
If-Match | header | string | Yes | Quoted positive current resource revision. |
|---|
Responses
deleteStreamGroup Responses| Status | Description |
|---|
204 | Group deleted after detaching nothing; still-referenced groups conflict. |
|---|
400 | Stable invalid request or validation error. |
|---|
401 | Authentication is missing or invalid. |
|---|
403 | The authenticated principal lacks the required permission or owner scope. |
|---|
404 | No visible stream matches the exact immutable stream identity. |
|---|
409 | Revision, idempotency, name, or listener-port conflict. |
|---|
500 | Internal operation failure without publication or activation claims. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list