Operation details
GET /v1/node-line-groups
查询线路组当前修订列表
- operationId
listNodeLineGroups- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
listNodeLineGroups Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
Responses
listNodeLineGroups Responses| Status | Description |
|---|
200 | Current immutable revision of every visible line group. Fields：items: array<LineGroupRevision> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.
↑ Back to list
POST /v1/node-line-groups
创建线路组首个不可变修订
- operationId
createNodeLineGroup- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
租户会话管理自身作用域；平台会话未指定 target_scope_id 时管理本主控平台作用域，显式指定租户作用域时拒绝写入。
Parameters
createNodeLineGroup Parameters| Name | In | Type | Required | Description |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | Yes | Must be the single exact quoted value "0". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createNodeLineGroup Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
region | string | No | — |
|---|
resolved_value | string | No | 留空时由服务端生成稳定的小写 DNS 标签；不要填写域名后缀、端口或 IP。 |
|---|
ipv4_resolved_value | string | No | IPv4 专用解析值；留空时由服务端按线路组 ID 生成稳定的小写 DNS 标签。 |
|---|
l2_config_id | string(uuid) | null(uuid) | No | 同一作用域、同一区域且未引用其他 L2 配置的活动线路组；为空表示独立线路组。 |
|---|
failover_mode | string: primary_offline / online_less_than_backup_count | No | 有主IP下线时逐个启用备用IP，或在线主IP数少于备用IP数时启用全部备用IP。 |
|---|
note | string | No | — |
|---|
sort_order | integer(int32) | No | — |
|---|
health_policy | HealthPolicy | Yes | — |
|---|
endpoints | array<EndpointWrite> | Yes | — |
|---|
Responses
createNodeLineGroup Responses| Status | Description |
|---|
201 | Revision 1 created. ETag is a quoted decimal revision. Fields：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
GET /v1/node-line-groups/{id}
查询线路组当前修订
- operationId
getNodeLineGroup- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getNodeLineGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
Responses
getNodeLineGroup Responses| Status | Description |
|---|
200 | Current immutable revision. Fields：id: string(uuid) display_id: string tenant_scope_id: string(uuid) revision: integer(int64) name: string region: string resolved_value: string ipv4_resolved_value: string l2_config_id: string(uuid) | null(uuid) failover_mode: string: primary_offline / online_less_than_backup_count note: string sort_order: integer(int32) health_policy: HealthPolicy endpoints: array<Endpoint> statistics?: LineGroupStatistics configuration_digest: string created_by_user_id: string(uuid) created_at: string(date-time) sealed_at: string(date-time) is_platform_default?: boolean backup_states?: array<LineBackupState> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.
↑ Back to list
PUT /v1/node-line-groups/{id}
创建线路组下一不可变修订
- operationId
updateNodeLineGroup- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
租户会话管理自身作用域；平台会话未指定 target_scope_id 时管理本主控平台作用域，显式指定租户作用域时拒绝写入。
Parameters
updateNodeLineGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | Yes | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updateNodeLineGroup Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
region | string | No | — |
|---|
resolved_value | string | No | 留空时由服务端生成稳定的小写 DNS 标签；不要填写域名后缀、端口或 IP。 |
|---|
ipv4_resolved_value | string | No | IPv4 专用解析值；留空时由服务端按线路组 ID 生成稳定的小写 DNS 标签。 |
|---|
l2_config_id | string(uuid) | null(uuid) | No | 同一作用域、同一区域且未引用其他 L2 配置的活动线路组；为空表示独立线路组。 |
|---|
failover_mode | string: primary_offline / online_less_than_backup_count | No | 有主IP下线时逐个启用备用IP，或在线主IP数少于备用IP数时启用全部备用IP。 |
|---|
note | string | No | — |
|---|
sort_order | integer(int32) | No | — |
|---|
health_policy | HealthPolicy | Yes | — |
|---|
endpoints | array<EndpointWrite> | Yes | — |
|---|
Responses
updateNodeLineGroup Responses| Status | Description |
|---|
200 | New immutable current revision. Fields：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
DELETE /v1/node-line-groups/{id}
软删除线路组并保留不可变修订历史
- operationId
deleteNodeLineGroup- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
租户会话删除自身作用域线路组；平台会话未指定 target_scope_id 时删除本主控平台作用域线路组，显式指定租户作用域时返回 403。删除后列表、当前详情、历史详情、探测与新拓扑快照入口均不可见；同一幂等键可重放。
Parameters
deleteNodeLineGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | Yes | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
deleteNodeLineGroup Responses| Status | Description |
|---|
204 | Soft deletion completed or the stored result was replayed. |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
401 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
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.
↑ Back to list
POST /v1/node-line-groups/{id}/decisions
计算可审计的区域健康调度决策
- operationId
decideNodeLineGroupEndpoint- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
decideNodeLineGroupEndpoint Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
decideNodeLineGroupEndpoint Request body| Name | Type | Required | Description |
|---|
selector | Selector | Yes | — |
|---|
requested_mode | string: weighted_baseline / weighted_rendezvous / p2c_least_loaded | Yes | — |
|---|
stable_key | string | Yes | — |
|---|
Responses
decideNodeLineGroupEndpoint Responses| Status | Description |
|---|
200 | Deterministic selection with auditable reason and fallback state. Fields：endpoint: Endpoint requested_mode: string: weighted_baseline / weighted_rendezvous / p2c_least_loaded effective_mode: string: weighted_baseline / weighted_rendezvous / p2c_least_loaded reason: string: baseline_weighted_selected / weighted_rendezvous_selected / p2c_least_loaded_selected / telemetry_insufficient / telemetry_stale_fallback / telemetry_unavailable_fallback / single_candidate_fallback / no_healthy_endpoint fallback: boolean priority: integer candidates: array<Endpoint> standby: array<Endpoint> snapshot: DecisionSnapshot |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.
↑ Back to list
设为或取消平台默认线路组
- operationId
setNodeLineGroupPlatformDefault- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
只限平台作用域普通线路组；设为默认会取消原默认。不推进线路组修订。没选套餐的网站用它冻结 CNAME 目标 IP。
Parameters
setNodeLineGroupPlatformDefault Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
setNodeLineGroupPlatformDefault Request body| Name | Type | Required | Description |
|---|
is_platform_default | boolean | Yes | — |
|---|
Responses
setNodeLineGroupPlatformDefault Responses| Status | Description |
|---|
200 | Current line group with the new platform default flag. Fields：group: LineGroupRevision |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.
↑ Back to list
GET /v1/node-line-groups/{id}/revisions/{revision}
查询线路组历史修订
- operationId
getNodeLineGroupRevision- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getNodeLineGroupRevision Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
revision | path | integer(int64) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
Responses
getNodeLineGroupRevision Responses| Status | Description |
|---|
200 | Historical immutable revision. Fields：id: string(uuid) display_id: string tenant_scope_id: string(uuid) revision: integer(int64) name: string region: string resolved_value: string ipv4_resolved_value: string l2_config_id: string(uuid) | null(uuid) failover_mode: string: primary_offline / online_less_than_backup_count note: string sort_order: integer(int32) health_policy: HealthPolicy endpoints: array<Endpoint> statistics?: LineGroupStatistics configuration_digest: string created_by_user_id: string(uuid) created_at: string(date-time) sealed_at: string(date-time) is_platform_default?: boolean backup_states?: array<LineBackupState> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.
↑ Back to list
POST /v1/node-line-groups/{id}/rollback
将历史配置复制为新的当前修订
- operationId
rollbackNodeLineGroup- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
rollbackNodeLineGroup Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
If-Match | header | string | Yes | Single quoted positive decimal current revision, for example "3". |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
rollbackNodeLineGroup Request body| Name | Type | Required | Description |
|---|
source_revision | integer(int64) | Yes | — |
|---|
Responses
rollbackNodeLineGroup Responses| Status | Description |
|---|
200 | Historical configuration copied into current revision plus one. Fields：group: LineGroupRevision replayed: boolean |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
409 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
↑ Back to list
GET /v1/node-line-groups/{id}/target-snapshots
按来源修订查询 L1/L2 拓扑快照
- operationId
getNodeLineGroupTargetSnapshot- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getNodeLineGroupTargetSnapshot Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
source_revision | query | integer(int64) | Yes | Single positive decimal source line-group revision. |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
Responses
getNodeLineGroupTargetSnapshot Responses| Status | Description |
|---|
200 | Immutable L1 target set bound to the requested L2 source revision. Fields：id: string(uuid) revision: integer(int64) tenant_scope_id: string(uuid) source_line_group_id: string(uuid) source_revision: integer(int64) source_configuration_digest: string node_set_digest: string node_ids: array<string(uuid)> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
403 | Stable error envelope; messages are not localization keys. |
|---|
404 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.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.
↑ Back to list
POST /v1/node-line-groups/{id}/target-snapshots
创建 L1 目标与 L2 候选拓扑快照
- operationId
createNodeLineGroupTargetSnapshot- Auth
- 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
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
createNodeLineGroupTargetSnapshot Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
target_scope_id | query | string(uuid) | No | Tenant credentials may omit this value or repeat their own scope. Platform Bearer credentials omit it to target the platform scope; an explicit tenant scope is allowed only on read or decision operations. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createNodeLineGroupTargetSnapshot Request body| Name | Type | Required | Description |
|---|
source_revision | integer(int64) | Yes | — |
|---|
node_ids | array<string(uuid)> | Yes | L1 target nodes. Every target has an edge to every L2 endpoint node in the source revision. |
|---|
Responses
createNodeLineGroupTargetSnapshot Responses| Status | Description |
|---|
201 | Immutable L1 target set bound to an immutable L2 source revision. Fields：id: string(uuid) revision: integer(int64) tenant_scope_id: string(uuid) source_line_group_id: string(uuid) source_revision: integer(int64) source_configuration_digest: string node_set_digest: string node_ids: array<string(uuid)> |
|---|
400 | Stable error envelope; messages are not localization keys. |
|---|
default | Stable error envelope; messages are not localization keys. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.
↑ Back to list