API reference

`/v1/streams`

7 operations · 7 support API keys

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

Method	Path	Summary	Auth
GET	`/v1/streams`	List layer-four forwarding rules	API keySession
POST	`/v1/streams`	Create a forwarding rule and immutable publication intent	API keySession
POST	`/v1/streams/batch`	批量添加 forwarding rules, one per line	API keySession
POST	`/v1/streams/batch-action`	更多操作 on selected forwarding rules (platform)	API keySession
GET	`/v1/streams/{id}`	Get one layer-four forwarding rule	API keySession
PATCH	`/v1/streams/{id}`	Replace a rule and create an immutable publication intent	API keySession
DELETE	`/v1/streams/{id}`	Soft-delete a rule and create a deletion publication intent	API keySession

Contract file：api/control-l4-forward.openapi.yaml

Operation details

GET `/v1/streams`

List layer-four forwarding rules

operationId

listStreams

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 rules owned by their current user and tenant. Platform principals can list tenant rules after streams.read authorization. All supplied filters are combined with AND and apply to both items and total. Unknown or repeated query parameters are rejected. protocol, enabled, listen_port, upstream, display_id, owner_display_id, publication_state, group_id, package_product_id, cname_domain, cname_hostname, region_id, node_group_id, sync_state and admin_status reject empty values.

Parameters

listStreams 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	—
`protocol`	query	`string: tcp / udp`	No	Exact lowercase tcp or udp matching any primary or additional listener. When listen_port is supplied, both must match the same listener. Whitespace and other spellings are rejected.
`enabled`	query	`boolean`	No	Exact lowercase true or false; whitespace, numbers and other spellings are rejected.
`listen_port`	query	`integer`	No	Exact listening port, written as a canonical positive decimal integer.
`upstream`	query	`string`	No	Case-insensitive literal substring of the upstream IP address or hostname. Surrounding whitespace is trimmed; SQL wildcard characters remain literal. Control characters and invalid UTF-8 are rejected.
`display_id`	query	`string`	No	Exact display ID as a canonical positive decimal string, at most 9223372036854775807. Display IDs are tenant-scoped.
`owner_display_id`	query	`string`	No	Exact stable user display number, written as a canonical positive decimal string at most 9223372036854775807. This is not a user UUID. Tenant principals remain restricted to their own scope and user; a different owner number returns an empty page.
`forward`	query	`string`	No	Case-insensitive substring of the forward name or remark (the name form of display_id).
`owner`	query	`string`	No	Platform only. Case-insensitive substring of the owner's username or display name (the name form of owner_display_id); tenant principals get 403.
`publication_state`	query	`string: unknown / pending / leased / retrying / reconciling / succeeded / failed / superseded`	No	Exact publish_intent.state of the latest intent and its latest automatic publication observation. retry_wait is exposed as retrying; missing or unrecognized observations are unknown. This is not a business eligibility status or an independently inferred edge synchronization result.
`group_id`	query	`string(uuid)`	No	Exact active stream group membership in the stream scope. This is a stream group, not a node line group.
`package_product_id`	query	`string(uuid)`	No	Exact package product referenced by the stream subscription in the same tenant scope, not a subscription ID.
`cname_domain`	query	`string`	No	Case-insensitive literal substring of the effective CNAME domain (the stream's own, else its package's).
`cname_hostname`	query	`string`	No	Case-insensitive literal substring of the package CNAME hostname (按套餐 streams).
`region_id`	query	`string(uuid)`	No	区域. Exact line.region_id (the stream's own region, else its package's). Platform principals only; tenant principals get 403.
`node_group_id`	query	`string(uuid)`	No	线路分组. Exact line.node_group_id (the stream's own line group, else its package's primary group). Platform principals only; tenant principals get 403.
`sync_state`	query	`string: done / pending / failed`	No	同步状态. Exact sync_state, derived from the latest intent's automatic publication and its node deployment receipts.
`admin_status`	query	`string: normal / locked / traffic_exceeded / package_expired`	No	状态. Exact admin_status.

Responses

listStreams Responses
Status	Description
`200`	Stable page ordered newest first. Fields：`items: array<Stream>` `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/streams`

Create a forwarding rule and immutable publication intent

operationId

createStream

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. The committed publication intent does not claim delivery or edge activation.

Parameters

createStream 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

createStream Request body
Name	Type	Required	Description
`package_subscription_id`	`string(uuid)`	No	The stream's package subscription (所属套餐). A stream belongs to no website; its line, CNAME, usage and stream_ports quota are the package's unless it sets its own line / CNAME.
`name`	`string`	No	—
`remark`	`string`	No	—
`protocol`	`string: tcp / udp`	No	—
`listen_address`	`string`	No	The current runtime binds wildcard IPv4 and IPv6 listeners.
`listen_port`	`integer`	No	—
`listen_port_end`	`integer`	No	端口范围. When non-zero the primary listener is listen_port..listen_port_end (greater than listen_port, at most 1000 ports), each port a socket of its own that counts against the package's stream_ports. A range may not cover the node ports 80/443/18080/18443, overlap a website port or another stream's socket of the same protocol, nor be TLS passthrough; such saves are refused with stream_port_conflict whose details say where. v2 streams only. Requires TCP/UDP capability API version 9 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`upstream_follow_port`	`boolean`	No	跟随端口回源. Connect to the origin on the port the client connected to (for a range, the matching port). upstream_port is then stored as listen_port and may be omitted. v2 streams only. Requires TCP/UDP capability API version 9.
`additional_listeners`	`array<StreamAdditionalListener>`	No	Extra listeners sharing this stream's endpoint, DNS and Geo policies. IDs are required client-generated UUIDs, globally distinct from every stream and other listener ID; IDs are returned in canonical order. Omitted on create means none; omitted on update preserves existing extras; an explicit empty array removes them. Any UDP listener requires both PROXY flags false. Active protocol and port pairs are reserved globally, including disabled streams, until removal or stream deletion.
`upstream_address`	`any \| any \| any`	No	—
`upstream_host`	`string`	No	Canonical lowercase IDNA host in stored responses.
`upstream_port`	`integer`	No	—
`dns_policy`	`StreamDNSPolicyZero \| StreamDNSPolicy`	No	—
`geo_policy`	`StreamGeoPolicy`	No	—
`connect_timeout_ms`	`integer`	No	—
`response_timeout_ms`	`integer`	No	—
`max_connections_per_client`	`integer`	No	—
`proxy_protocol_inbound`	`boolean`	No	Must be true exactly when enabled geo source resolution uses trusted_proxy_cidrs.
`proxy_protocol_v1`	`boolean`	No	Outbound Proxy Protocol v1; TCP only.
`tls_passthrough`	`boolean`	No	Forward TLS unterminated and pick this stream by SNI, so several streams, websites and at most one plain TCP stream can share the TCP port. TCP only, including every additional listener. Non-TLS connections go to the plain TCP stream on the port; TLS connections whose SNI matches nothing are closed.
`server_names`	`array<string>`	No	SNI of a TLS passthrough stream, 1-32 names, empty otherwise. Exact names win over wildcards. Each (port, name) is reserved globally while the stream is live; "*.a.com" and "x.a.com" are distinct names. Stored responses are lower-case and sorted.
`max_new_connections_per_client_per_second`	`integer`	No	单 IP 新建连接速率. New connections (UDP sessions) one client IP may open to this stream per second, shared by all its listeners; 0 is unlimited. The client is the PROXY protocol address when the peer is a trusted proxy. Requires TCP/UDP capability API version 6 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`new_connection_burst`	`integer`	No	Connections allowed at once beyond the per-second rate (bucket capacity is rate + burst). Must be 0 when the rate is 0.
`new_connection_ban_seconds`	`integer`	No	0 refuses only connections over the rate; otherwise a client over the rate is refused new connections to this stream for this many seconds (node-local). Must be 0 when the rate is 0.
`toa`	`boolean`	No	回源携带客户端 IP via TOA. The node writes the IPv4 client address and port into TCP option 254 (length 8) on the handshake ACK towards the origin; the origin needs a TOA module. IPv6 clients are forwarded without the option. TCP only (all listeners); excludes proxy_protocol_v1 and proxy_protocol_inbound. Requires capability L4_TOA v1 on every target node (Linux 5.10+ with the node's eBPF probe passing); otherwise publication is refused with node_capability_unavailable naming the nodes.
`session_log_enabled`	`boolean`	No	会话日志. Write a per-session access log (client IP — the PROXY protocol address when the peer is a trusted proxy — upstream, bytes, duration and end reason, refused sessions included) and register live TCP sessions for the real-time connection list. v2 streams only. Requires TCP/UDP capability API version 7 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`guard_rules`	`array<StreamGuardRule>`	No	防护规则. Evaluated in order on each new connection (UDP session) at the node; the first rule whose conditions all hold decides. Omitted or empty is none; responses always carry the array. v2 streams only. Requires TCP/UDP capability API version 10 on every target node; a rule with a geo condition also requires IP_INTEL v2 and a verified IP intelligence library on every target node. Otherwise publication is refused with node_capability_unavailable naming the nodes.
`origins`	`array<StreamOrigin>`	No	源站列表. Several origins on upstream_port, each with a weight (1..100, share of new connections) and down (下线, gets none); at least one up. Several origins are IP addresses; a single origin may be a domain name (then dns_policy applies). When sent, upstream_address/upstream_host are taken from the first origin; omitted keeps the single upstream_address/upstream_host. Responses always carry the list (one entry, weight 1, for a single origin). Not with upstream_follow_port when several. Several origins, or balance_way ip_hash, require TCP/UDP capability API version 11 on every target node.
`listen_ipv6`	`boolean`	No	IPv6开启. The node also listens on [::] for the stream's own sockets. Requires TCP/UDP capability API version 11.
`acl`	`StreamACL`	No	访问控制 IP rules. Rules are evaluated in order, the first matching rule decides; otherwise default_action (默认允许 allow / 默认拒绝 deny). The node enforces them as the stream's leading guard rules (client_ip allow / drop), ahead of guard_rules, so they need TCP/UDP capability API version 10 and count against the platform ACL rule limit together with guard_rules. Omitted on a write keeps default allow without rules.
`enabled`	`boolean`	No	—
`balance_way`	`string: rr / ip_hash`	No	Origin connection balancing strategy; this is independent of the selected node line group.
`groups`	`array<StreamGroupReference>`	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.
`group_ids`	`array<string(uuid)>`	No	Groups in the same scope; omitted or empty means ungrouped.

Responses

createStream Responses
Status	Description
`201`	Rule and publication intent committed atomically, or an exact idempotent replay returned. Fields：`package_subscription_id?: string(uuid)` `name?: string` `remark?: string` `protocol?: string: tcp / udp` `listen_address?: string` `listen_port?: integer` `listen_port_end?: integer` `upstream_follow_port?: boolean` `additional_listeners?: array<StreamAdditionalListener>` `upstream_address?: any \| any \| any` `upstream_host?: string` `upstream_port?: integer` `dns_policy?: StreamDNSPolicyZero \| StreamDNSPolicy` `geo_policy: StreamGeoPolicy` `connect_timeout_ms?: integer` `response_timeout_ms?: integer` `max_connections_per_client?: integer` `proxy_protocol_inbound?: boolean` `proxy_protocol_v1?: boolean` `tls_passthrough?: boolean` `server_names?: array<string>` `max_new_connections_per_client_per_second?: integer` `new_connection_burst?: integer` `new_connection_ban_seconds?: integer` `toa?: boolean` `session_log_enabled?: boolean` `guard_rules?: array<StreamGuardRule>` `origins?: array<StreamOrigin>` `listen_ipv6?: boolean` `acl?: StreamACL` `enabled?: boolean` `balance_way?: string: rr / ip_hash` `groups?: array<StreamGroupReference>` `id: string(uuid)` `display_id: string` `scope_id: string(uuid)` `package_name?: string \| null` `package_expires_at?: string(date-time) \| null(date-time)` `cname?: string \| null` `cname_domain?: string \| null` `cname_hostname?: string \| null` `cname_state?: string: pending / failed / done / null \| null: pending / failed / done / null` `cname_failure_code?: string \| null` `eligibility_state: string: eligible / ineligible` `admin_status: string: normal / locked / traffic_exceeded / package_expired` `overrides: StreamOverrides` `line: StreamLine` `sync_state: string: done / pending / failed` `owner: StreamOwner \| null` `revision: integer(int64)` `publish_intent: StreamPublishIntent` `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

POST `/v1/streams/batch`

批量添加 forwarding rules, one per line

operationId

batchCreateStreams

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)

Each line is "监听端口|IP|回源端口", e.g. "88 99/udp|1.2.3.4|8080": the first port (default tcp, "/udp" or "/tcp" suffix) is the primary listener, the others additional listeners; the origin is an IP address or a domain name. template holds the fields every line shares (package, remark, timeouts, DNS policy for domain origins, …); its listen and origin fields are ignored. Lines are validated and written in order. With ignore_errors (忽略错误) a failed line is skipped and the others are committed (200). Without it the batch is atomic: one failed line and nothing is written (422, the failed line says why, the rest are skipped). The idempotency key covers the whole batch.

Parameters

batchCreateStreams 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

batchCreateStreams Request body
Name	Type	Required	Description
`target_scope_id`	`string(uuid)`	No	Required for platform principals.
`owner_id`	`string(uuid)`	No	Required for platform principals.
`group_ids`	`array<string(uuid)>`	No	—
`template`	`StreamFields`	Yes	—
`lines`	`array<string>`	Yes	—
`ignore_errors`	`boolean`	No	—

Responses

batchCreateStreams Responses
Status	Description
`200`	Committed; failed lines (only with ignore_errors) are listed with their error. Fields：`items: array<object>` `created: integer` `failed: integer` `committed: boolean`
`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.
`422`	Without ignore_errors a line failed; nothing was written (committed false).
`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

POST `/v1/streams/batch-action`

更多操作 on selected forwarding rules (platform)

operationId

batchStreamAction

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)

Platform principals only. set_status (设置状态) sets admin_status; a status other than normal takes the stream off the nodes until it is normal again. cname_domain (修改CNAME域名), cname_mode (修改CNAME生成模式) and line_group (修改线路分组: region_id, node_group_id, backup_node_group_id) set the stream's own overrides; "" / an omitted id clears one, so the stream follows its package. A stream's line group (its own, else its package's) adds its nodes to the scope's publication targets. Each item carries its own expected_revision and is applied alone: a missing or stale item fails with its code (stream_not_found, version_conflict, and for cname_regenerate stream_cname_not_overridden / stream_cname_not_failed) and the others are applied.

Parameters

batchStreamAction 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

batchStreamAction Request body
Name	Type	Required	Description
`action`	`string: set_status / cname_domain / cname_mode / line_group / cname_regenerate`	Yes	—
`admin_status`	`string: normal / locked / traffic_exceeded / package_expired`	No	状态 (设置状态). Only normal streams are served.
`cname_domain`	`string`	No	A CNAME domain of 节点管理 > DNS配置, or "" to follow the package.
`cname_mode`	`string: / site / package`	No	按转发生成 (site) / 按套餐生成 (package), or "" to follow the package.
`region_id`	`string(uuid)`	No	A platform region; omitted to follow the package.
`node_group_id`	`string(uuid)`	No	A live platform general line group; omitted to follow the package.
`backup_node_group_id`	`string(uuid)`	No	A live platform general line group other than node_group_id.
`items`	`array<object>`	Yes	—

Responses

batchStreamAction Responses
Status	Description
`200`	Per-item results in request order. Fields：`items: array<object>`
`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

GET `/v1/streams/{id}`

Get one layer-four forwarding rule

operationId

getStream

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)

Returns the current rule and its latest exact publication intent projection.

Parameters

getStream Parameters
Name	In	Type	Required	Description
`id`	path	`string(uuid)`	Yes	Exact immutable stream identity.
`X-Request-ID`	header	`string`	No	Caller-stable request identity; invalid or absent values are replaced by middleware.

Responses

getStream Responses
Status	Description
`200`	Current rule and latest exact publication intent. Fields：`package_subscription_id?: string(uuid)` `name?: string` `remark?: string` `protocol?: string: tcp / udp` `listen_address?: string` `listen_port?: integer` `listen_port_end?: integer` `upstream_follow_port?: boolean` `additional_listeners?: array<StreamAdditionalListener>` `upstream_address?: any \| any \| any` `upstream_host?: string` `upstream_port?: integer` `dns_policy?: StreamDNSPolicyZero \| StreamDNSPolicy` `geo_policy: StreamGeoPolicy` `connect_timeout_ms?: integer` `response_timeout_ms?: integer` `max_connections_per_client?: integer` `proxy_protocol_inbound?: boolean` `proxy_protocol_v1?: boolean` `tls_passthrough?: boolean` `server_names?: array<string>` `max_new_connections_per_client_per_second?: integer` `new_connection_burst?: integer` `new_connection_ban_seconds?: integer` `toa?: boolean` `session_log_enabled?: boolean` `guard_rules?: array<StreamGuardRule>` `origins?: array<StreamOrigin>` `listen_ipv6?: boolean` `acl?: StreamACL` `enabled?: boolean` `balance_way?: string: rr / ip_hash` `groups?: array<StreamGroupReference>` `id: string(uuid)` `display_id: string` `scope_id: string(uuid)` `package_name?: string \| null` `package_expires_at?: string(date-time) \| null(date-time)` `cname?: string \| null` `cname_domain?: string \| null` `cname_hostname?: string \| null` `cname_state?: string: pending / failed / done / null \| null: pending / failed / done / null` `cname_failure_code?: string \| null` `eligibility_state: string: eligible / ineligible` `admin_status: string: normal / locked / traffic_exceeded / package_expired` `overrides: StreamOverrides` `line: StreamLine` `sync_state: string: done / pending / failed` `owner: StreamOwner \| null` `revision: integer(int64)` `publish_intent: StreamPublishIntent` `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.
`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.
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/streams/{id}`

Replace a rule and create an immutable publication intent

operationId

updateStream

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)

If-Match and expected_revision must contain the same quoted positive revision. Ownership is retained; no owner or scope field is accepted.

Parameters

updateStream Parameters
Name	In	Type	Required	Description
`id`	path	`string(uuid)`	Yes	Exact immutable stream 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

updateStream Request body
Name	Type	Required	Description
`package_subscription_id`	`string(uuid)`	No	The stream's package subscription (所属套餐). A stream belongs to no website; its line, CNAME, usage and stream_ports quota are the package's unless it sets its own line / CNAME.
`name`	`string`	No	—
`remark`	`string`	No	—
`protocol`	`string: tcp / udp`	No	—
`listen_address`	`string`	No	The current runtime binds wildcard IPv4 and IPv6 listeners.
`listen_port`	`integer`	No	—
`listen_port_end`	`integer`	No	端口范围. When non-zero the primary listener is listen_port..listen_port_end (greater than listen_port, at most 1000 ports), each port a socket of its own that counts against the package's stream_ports. A range may not cover the node ports 80/443/18080/18443, overlap a website port or another stream's socket of the same protocol, nor be TLS passthrough; such saves are refused with stream_port_conflict whose details say where. v2 streams only. Requires TCP/UDP capability API version 9 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`upstream_follow_port`	`boolean`	No	跟随端口回源. Connect to the origin on the port the client connected to (for a range, the matching port). upstream_port is then stored as listen_port and may be omitted. v2 streams only. Requires TCP/UDP capability API version 9.
`additional_listeners`	`array<StreamAdditionalListener>`	No	Extra listeners sharing this stream's endpoint, DNS and Geo policies. IDs are required client-generated UUIDs, globally distinct from every stream and other listener ID; IDs are returned in canonical order. Omitted on create means none; omitted on update preserves existing extras; an explicit empty array removes them. Any UDP listener requires both PROXY flags false. Active protocol and port pairs are reserved globally, including disabled streams, until removal or stream deletion.
`upstream_address`	`any \| any \| any`	No	—
`upstream_host`	`string`	No	Canonical lowercase IDNA host in stored responses.
`upstream_port`	`integer`	No	—
`dns_policy`	`StreamDNSPolicyZero \| StreamDNSPolicy`	No	—
`geo_policy`	`StreamGeoPolicy`	No	—
`connect_timeout_ms`	`integer`	No	—
`response_timeout_ms`	`integer`	No	—
`max_connections_per_client`	`integer`	No	—
`proxy_protocol_inbound`	`boolean`	No	Must be true exactly when enabled geo source resolution uses trusted_proxy_cidrs.
`proxy_protocol_v1`	`boolean`	No	Outbound Proxy Protocol v1; TCP only.
`tls_passthrough`	`boolean`	No	Forward TLS unterminated and pick this stream by SNI, so several streams, websites and at most one plain TCP stream can share the TCP port. TCP only, including every additional listener. Non-TLS connections go to the plain TCP stream on the port; TLS connections whose SNI matches nothing are closed.
`server_names`	`array<string>`	No	SNI of a TLS passthrough stream, 1-32 names, empty otherwise. Exact names win over wildcards. Each (port, name) is reserved globally while the stream is live; "*.a.com" and "x.a.com" are distinct names. Stored responses are lower-case and sorted.
`max_new_connections_per_client_per_second`	`integer`	No	单 IP 新建连接速率. New connections (UDP sessions) one client IP may open to this stream per second, shared by all its listeners; 0 is unlimited. The client is the PROXY protocol address when the peer is a trusted proxy. Requires TCP/UDP capability API version 6 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`new_connection_burst`	`integer`	No	Connections allowed at once beyond the per-second rate (bucket capacity is rate + burst). Must be 0 when the rate is 0.
`new_connection_ban_seconds`	`integer`	No	0 refuses only connections over the rate; otherwise a client over the rate is refused new connections to this stream for this many seconds (node-local). Must be 0 when the rate is 0.
`toa`	`boolean`	No	回源携带客户端 IP via TOA. The node writes the IPv4 client address and port into TCP option 254 (length 8) on the handshake ACK towards the origin; the origin needs a TOA module. IPv6 clients are forwarded without the option. TCP only (all listeners); excludes proxy_protocol_v1 and proxy_protocol_inbound. Requires capability L4_TOA v1 on every target node (Linux 5.10+ with the node's eBPF probe passing); otherwise publication is refused with node_capability_unavailable naming the nodes.
`session_log_enabled`	`boolean`	No	会话日志. Write a per-session access log (client IP — the PROXY protocol address when the peer is a trusted proxy — upstream, bytes, duration and end reason, refused sessions included) and register live TCP sessions for the real-time connection list. v2 streams only. Requires TCP/UDP capability API version 7 on every target node; otherwise publication is refused with node_capability_unavailable naming the nodes.
`guard_rules`	`array<StreamGuardRule>`	No	防护规则. Evaluated in order on each new connection (UDP session) at the node; the first rule whose conditions all hold decides. Omitted or empty is none; responses always carry the array. v2 streams only. Requires TCP/UDP capability API version 10 on every target node; a rule with a geo condition also requires IP_INTEL v2 and a verified IP intelligence library on every target node. Otherwise publication is refused with node_capability_unavailable naming the nodes.
`origins`	`array<StreamOrigin>`	No	源站列表. Several origins on upstream_port, each with a weight (1..100, share of new connections) and down (下线, gets none); at least one up. Several origins are IP addresses; a single origin may be a domain name (then dns_policy applies). When sent, upstream_address/upstream_host are taken from the first origin; omitted keeps the single upstream_address/upstream_host. Responses always carry the list (one entry, weight 1, for a single origin). Not with upstream_follow_port when several. Several origins, or balance_way ip_hash, require TCP/UDP capability API version 11 on every target node.
`listen_ipv6`	`boolean`	No	IPv6开启. The node also listens on [::] for the stream's own sockets. Requires TCP/UDP capability API version 11.
`acl`	`StreamACL`	No	访问控制 IP rules. Rules are evaluated in order, the first matching rule decides; otherwise default_action (默认允许 allow / 默认拒绝 deny). The node enforces them as the stream's leading guard rules (client_ip allow / drop), ahead of guard_rules, so they need TCP/UDP capability API version 10 and count against the platform ACL rule limit together with guard_rules. Omitted on a write keeps default allow without rules.
`enabled`	`boolean`	No	—
`balance_way`	`string: rr / ip_hash`	No	Origin connection balancing strategy; this is independent of the selected node line group.
`groups`	`array<StreamGroupReference>`	No	—
`expected_revision`	`integer(int64)`	Yes	Must exactly equal the quoted If-Match revision.
`group_ids`	`array<string(uuid)>`	No	Omitted keeps current membership; an empty array clears it.

Responses

updateStream Responses
Status	Description
`200`	Rule and publication intent committed atomically, or an exact idempotent replay returned. Fields：`package_subscription_id?: string(uuid)` `name?: string` `remark?: string` `protocol?: string: tcp / udp` `listen_address?: string` `listen_port?: integer` `listen_port_end?: integer` `upstream_follow_port?: boolean` `additional_listeners?: array<StreamAdditionalListener>` `upstream_address?: any \| any \| any` `upstream_host?: string` `upstream_port?: integer` `dns_policy?: StreamDNSPolicyZero \| StreamDNSPolicy` `geo_policy: StreamGeoPolicy` `connect_timeout_ms?: integer` `response_timeout_ms?: integer` `max_connections_per_client?: integer` `proxy_protocol_inbound?: boolean` `proxy_protocol_v1?: boolean` `tls_passthrough?: boolean` `server_names?: array<string>` `max_new_connections_per_client_per_second?: integer` `new_connection_burst?: integer` `new_connection_ban_seconds?: integer` `toa?: boolean` `session_log_enabled?: boolean` `guard_rules?: array<StreamGuardRule>` `origins?: array<StreamOrigin>` `listen_ipv6?: boolean` `acl?: StreamACL` `enabled?: boolean` `balance_way?: string: rr / ip_hash` `groups?: array<StreamGroupReference>` `id: string(uuid)` `display_id: string` `scope_id: string(uuid)` `package_name?: string \| null` `package_expires_at?: string(date-time) \| null(date-time)` `cname?: string \| null` `cname_domain?: string \| null` `cname_hostname?: string \| null` `cname_state?: string: pending / failed / done / null \| null: pending / failed / done / null` `cname_failure_code?: string \| null` `eligibility_state: string: eligible / ineligible` `admin_status: string: normal / locked / traffic_exceeded / package_expired` `overrides: StreamOverrides` `line: StreamLine` `sync_state: string: done / pending / failed` `owner: StreamOwner \| null` `revision: integer(int64)` `publish_intent: StreamPublishIntent` `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/streams/{id}`

Soft-delete a rule and create a deletion publication intent

operationId

deleteStream

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

deleteStream Parameters
Name	In	Type	Required	Description
`id`	path	`string(uuid)`	Yes	Exact immutable stream 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

deleteStream Responses
Status	Description
`204`	Rule deleted and immutable deletion intent committed.
`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

/v1/streams

Operation details

GET /v1/streams

Description (from the contract)

Parameters

Responses

What to do on failure

POST /v1/streams

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

POST /v1/streams/batch

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

POST /v1/streams/batch-action

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

GET /v1/streams/{id}

Description (from the contract)

Parameters

Responses

What to do on failure

PATCH /v1/streams/{id}

Description (from the contract)

Parameters

Request body

Responses

What to do on failure

DELETE /v1/streams/{id}

Parameters

Responses

What to do on failure

`/v1/streams`

GET `/v1/streams`

POST `/v1/streams`

POST `/v1/streams/batch`

POST `/v1/streams/batch-action`

GET `/v1/streams/{id}`

PATCH `/v1/streams/{id}`

DELETE `/v1/streams/{id}`