接口详情
GET /v1/nodes
List platform nodes with explicit inventory order and keyset pagination
- operationId
listNodes- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in a platform scope. Search is always evaluated after scope isolation and matches node name or region by case-insensitive literal containment, a full UUID exactly, a canonical display ID prefix, or a normalized IPv4/IPv6 address exactly. platform.admin remains a wildcard permission. Without order, the existing UUID ascending order and cursor remain unchanged. With management_sort_desc, rows use persisted management sort, numeric display ID, then UUID descending; its opaque cursor is bound to the authorized scope and filters. Pages are live reads, not a snapshot.
参数
listNodes 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
status | query | string: pending / active / draining / disabled / retired | 否 | Exact admin state filter. Deleting a node removes it, so retired is not accepted here (validation_error); a retired row left by a release before physical deletion is listed without a filter and can be deleted. |
|---|
presence | query | string: online / offline / unknown | 否 | Effective presence derived from the confirmed PostgreSQL projection and the offline threshold. |
|---|
search | query | string | 否 | Optional literal node search. Surrounding whitespace is ignored; control characters are rejected. |
|---|
order | query | string: management_sort_desc | 否 | Omit for the unchanged UUID-ascending NodeListResponse. Explicit management_sort_desc requests persisted management_settings.sort DESC, numeric display_id DESC, internal UUID DESC and requires an order echo. nodes.read and the current platform scope are checked on every request. In this mode only order, status, presence, search, limit and cursor are accepted; unknown or repeated parameters return validation_error (400). Explicit empty/unknown order or cursor is invalid. Limit is 1..300, default 20. There is no ascending management-sort mode. |
|---|
cursor | query | string(uuid) | string | 否 | With no order, the existing last-node UUID. With management_sort_desc, the exact next_cursor returned for the same scope, status, presence and normalized search. Page size can change. Changing sort/filter/scope requires restarting at the first page. This is live keyset pagination, not a snapshot across concurrent writes. Cursors are untrusted bookmarks, not authorization; changing scope/filter/order returns validation_error. |
|---|
limit | query | integer | 否 | — |
|---|
响应
listNodes 响应| 状态码 | 说明 |
|---|
200 | Node page in the requested order; explicit order is echoed only for the ordered response. |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes
Create a pending platform node
- operationId
createNode- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope and a valid local entitlement granting nodes.manage plus nodes.count. The quota counts every platform node whose admin_state is not retired; disabled nodes still consume quota. Grace, expired, unavailable, missing-feature, and missing-quota states reject creation without interrupting existing nodes. The Idempotency-Key is scoped to the actor and operation. An identical replay returns the original node before evaluating the current lease or quota, but never returns or regenerates the one-time enrollment token. Reusing the key with different normalized input returns idempotency_conflict. platform.admin remains a wildcard RBAC permission but does not bypass entitlement.
参数
createNode 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createNode 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 否 | — |
|---|
region | string | 否 | — |
|---|
ipv4 | string(ipv4) | 否 | — |
|---|
ipv6 | string(ipv6) | 否 | — |
|---|
issue_enrollment_token | boolean | 否 | — |
|---|
enrollment_purpose | string: initial_enrollment / re_enrollment | 否 | — |
|---|
enrollment_token_ttl_seconds | integer | 否 | — |
|---|
响应
createNode 响应| 状态码 | 说明 |
|---|
201 | Node created, or the original result replayed. A requested raw enrollment token is shown only on the first successful response; it is absent on replay. 字段：node: Node enrollment_token?: IssuedEnrollmentToken |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/batch-admin-state
Update one administrative state across a batch of nodes
- operationId
batchUpdateNodeAdminState- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. The request accepts at most 100 unique node IDs and preserves input order in the response. Nodes are locked in UUID order, successful items and their audits commit in one transaction, and validation or state failures are returned per item. Replaying the same idempotency key with the same normalized request returns the stored result without another revision or audit event. admin_state retired is the batch delete; it follows updateNode. Each deletion runs in its own savepoint, so a node in use fails alone with node_in_use (or node_not_found) and the others are still deleted; a deleted item reports status updated with the last node snapshot. Disabling or draining the last online available node of a node-market supply that still has a normal subscriber fails that item with supply_in_use (with online_available and normal_subscriptions); items are checked in UUID order against the ones applied before them.
参数
batchUpdateNodeAdminState 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
batchUpdateNodeAdminState 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
admin_state | string: active / draining / disabled / retired | 是 | — |
|---|
items | array<BatchNodeAdminStateItem> | 是 | — |
|---|
响应
batchUpdateNodeAdminState 响应| 状态码 | 说明 |
|---|
200 | Ordered per-item results. Successful items are committed even when other items fail validation against current state. 字段：items: array<BatchNodeAdminStateItemResult> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/installation-tickets
Get each node's last license service ticket and the days left
- operationId
getNodeInstallationTickets- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
PF09. Requires nodes.read in the current platform scope. Supply only node_id, repeated once per unique canonical nonzero UUID (1 to 300). Each item is the ServiceTicket the node reported in its last installation ban receipt: valid (with days_left rounded down), expired (the node stopped serving), no_ticket (the node never received its first ticket and does not serve yet) or unknown (no receipt: the node has not connected since, or an old Agent). A node of another scope reads as unknown. Items preserve request order.
参数
getNodeInstallationTickets 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
node_id | query | array<string(uuid)> | 是 | — |
|---|
响应
getNodeInstallationTickets 响应| 状态码 | 说明 |
|---|
200 | One ticket view per requested node. 字段：observed_at: string(date-time) items: array<object> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/metrics/latest
Get latest durable load samples for a bounded set of platform nodes
- operationId
getLatestNodeMetricsBatch- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in the current platform scope. Supply only node_id, repeated once per unique canonical nonzero UUID (1 to 300 identifiers). Missing, duplicate, malformed or extra query parameters return 400 validation_error. Membership and samples are read in one database snapshot. Any nonexistent or other-scope node rejects the entire batch with the same 404 node_metrics_not_found; no partial results or foreign identifiers are returned. Existing in-scope nodes without a durable load sample appear in not_reported_node_ids. Those identifiers and items.node_id are disjoint and together cover the request exactly, with each array preserving request order. Each item is the unchanged single-node latest DTO, including unknown values, record_kind, original sample time, telemetry and durable delivery identity. No sample is fabricated from presence, and host_metric is not a probe-health decision. observed_at is the server UTC read time, not the sample time or a claim of freshness. Unavailable storage or batch runtime returns 503 node_metrics_unavailable. This endpoint does not aggregate monthly traffic.
参数
getLatestNodeMetricsBatch 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
node_id | query | array<string(uuid)> | 是 | — |
|---|
响应
getLatestNodeMetricsBatch 响应| 状态码 | 说明 |
|---|
200 | Complete scoped batch, with absent samples distinguished from measured values. 字段：observed_at: string(date-time) items: array<NodeMetricsLatest> not_reported_node_ids: array<string(uuid)> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/monitoring/latest
批量读取节点本机 TCP 探测事实与当前生效策略
- operationId
getLatestNodeMonitoring- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires a platform principal with nodes.read in the current scope. One read-only repeatable database snapshot covers membership, head/active configuration and probe-only node_metric_latest. Items cover the unique request IDs exactly in request order, with no partial results. Any absent or foreign node returns the same node_monitoring_not_found (404), without leaking sibling facts. Invalid/duplicate/unknown query parameters return validation_error (400); absent session invalid_session (401); non-platform or missing permission permission_denied (403). Unavailable storage or invalid persisted facts return node_monitoring_unavailable (503), not an empty snapshot. The configuration reader checks canonical_schema, canonical_snapshot, canonical bytes and SHA-256; this is no signature claim. It neither locks/creates a stream nor reconciles publications. Policy comes only from active_revision, never the editable head. A disabled policy is a request with no application ACK, not evidence that the node has stopped probing. Samples are actual agent_local_tcp only; host metrics and heartbeats are not probes. Requested HTTP/Ping protocols and distributed monitor groups are not execution proof; an executed pause appears as serving_holds.
参数
getLatestNodeMonitoring 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
node_id | query | array<string(uuid)> | 是 | 1–300 unique canonical lowercase nonzero UUIDs; no other query keys are accepted. |
|---|
响应
getLatestNodeMonitoring 响应| 状态码 | 说明 |
|---|
200 | 当前生效配置与实际探测事实；缺失数据保持 null。 字段：schema_version: integer observed_at: string(date-time) configuration: NodeMonitoringLatestConfiguration items: array<NodeMonitoringLatestItem> |
|---|
400 | validation_error |
|---|
401 | invalid_session |
|---|
403 | permission_denied |
|---|
404 | node_monitoring_not_found |
|---|
503 | node_monitoring_unavailable |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/registration-credential
Get the reusable node registration credential
- operationId
getNodeRegistrationCredential- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. Returns the scope-level credential embedded in the node install command (the same command for every node); issues the first credential when none exists. Viewing it never creates a node. Only the credential SHA-256 is persisted; the value is derived from a server-side secret. Responses are Cache-Control no-store.
响应
getNodeRegistrationCredential 响应| 状态码 | 说明 |
|---|
200 | Current credential. 字段：key_id: string(uuid) credential: string issued_at: string(date-time) |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/registration-credential/reset
Reset the node registration credential
- operationId
resetNodeRegistrationCredential- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. Issues a new credential; every previously copied install command is rejected from then on. Installed nodes keep their mTLS identity and are unaffected.
响应
resetNodeRegistrationCredential 响应| 状态码 | 说明 |
|---|
200 | New credential. 字段：key_id: string(uuid) credential: string issued_at: string(date-time) |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/{id}
Get one platform node
- operationId
getNode- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in a platform scope. platform.admin remains a wildcard permission.
参数
getNode 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getNode 响应| 状态码 | 说明 |
|---|
200 | Node inventory record. 字段：id: string(uuid) display_id: string name: string description: string region: string ipv4?: string(ipv4) ipv6?: string(ipv6) admin_state: string: pending / active / draining / disabled / retired management_settings: NodeManagementSettings revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) presence: NodePresence network_inventory?: NodeNetworkInventoryStatus |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/nodes/{id}
Update node inventory metadata or administrative state
- operationId
updateNode- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. If-Match supplies the expected revision. pending nodes cannot be activated or moved through an intermediate management state; first activation is reserved for the future Gateway CompleteEnrollment contract. disabled to active requires a node-bound consumed enrollment authorization. That authorization records permission to enroll only and does not prove certificate persistence, mTLS connectivity, or completed Gateway enrollment. retired is the delete operation and must be the only field: it physically deletes the node. It is rejected with node_in_use while the current revision of a live line group or a live L2 configuration lists the node, or while the node takes part in a queued or running cache operation or an active CC coordination. In one transaction it revokes the active certificates, writes a node.delete audit event (node ID, display ID, name, addresses, revoked certificate IDs and serial numbers, deleting user, time), and deletes the node row together with every row that only describes the node (certificates, identity, sessions, monitoring samples, deployment receipts, task projections). The response is the last node snapshot with admin_state retired. The Gateway ends the session on its next authorization refresh (at most 30 seconds) and rejects reconnects. The name and the licensed node slot are released at once; running the install command on the same host registers a new pending node, which may reuse the name but never the deleted node ID. Disabling or draining the last online available node (active, online, not isolated, not held) of a node-market supply that still has a normal subscriber is rejected with 409 supply_in_use, error.details {online_available, normal_subscriptions}; a supply already without online nodes is not blocked. Line groups only take nodes of their own region, so changing region is rejected with 409 node_region_in_use while the current revision of a live line group of another region lists the node (remove it from that line group first). When pending to active (initialize) leaves the node without a region and the region catalog has exactly one region, the node is put into that region; with several, the request may name one in region.
参数
updateNode 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateNode 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 否 | — |
|---|
description | string | 否 | — |
|---|
region | string | 否 | — |
|---|
ipv4 | string(ipv4) | string | 否 | An IPv4 address, or an empty string to clear the address. |
|---|
ipv6 | string(ipv6) | string | 否 | An IPv6 address, or an empty string to clear the address. |
|---|
admin_state | string: active / draining / disabled / retired | 否 | — |
|---|
management_settings | NodeManagementSettings | 否 | — |
|---|
响应
updateNode 响应| 状态码 | 说明 |
|---|
200 | Updated node, or the original response for an identical idempotent replay. 字段：id: string(uuid) display_id: string name: string description: string region: string ipv4?: string(ipv4) ipv6?: string(ipv6) admin_state: string: pending / active / draining / disabled / retired management_settings: NodeManagementSettings revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) presence?: NodePresence |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/{id}/enrollment-tokens
Issue a one-time enrollment token
- operationId
issueNodeEnrollmentToken- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. platform.admin remains a wildcard permission. The raw token is shown only in this response.
参数
issueNodeEnrollmentToken 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
请求体
application/json · 必填：是
issueNodeEnrollmentToken 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
purpose | string: initial_enrollment / re_enrollment | 否 | — |
|---|
ttl_seconds | integer | 否 | — |
|---|
响应
issueNodeEnrollmentToken 响应| 状态码 | 说明 |
|---|
201 | Token issued. 字段：id: string(uuid) node_id: string(uuid) purpose: string: initial_enrollment / re_enrollment created_at: string(date-time) expires_at: string(date-time) token: string |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/{id}/gateway-port-transitions
Start a versioned Agent Gateway communication-port transition
- operationId
createNodeGatewayPortTransition- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. The old and candidate listeners remain distinct until a durable Agent status permits finalize or rollback. A missing, disabled or unavailable command runtime returns 503 node_port_transition_runtime_unavailable before any command is queued. Runtime readiness alone does not prove endpoint reachability or Agent capability.
参数
createNodeGatewayPortTransition 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createNodeGatewayPortTransition 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_node_revision | integer(int64) | 是 | — |
|---|
old_endpoint | NodeGatewayEndpoint | 是 | — |
|---|
new_endpoint | NodeGatewayEndpoint | 是 | — |
|---|
compatibility_deadline | string(date-time) | 是 | — |
|---|
rollback_deadline | string(date-time) | 是 | — |
|---|
响应
createNodeGatewayPortTransition 响应| 状态码 | 说明 |
|---|
201 | Transition and durable switch command created, or the original result replayed. 字段：id: string(uuid) scope_id: string(uuid) node_id: string(uuid) revision: integer(int64) expected_node_revision: integer(int64) old_endpoint: NodeGatewayEndpoint new_endpoint: NodeGatewayEndpoint compatibility_deadline: string(date-time) rollback_deadline: string(date-time) state: string: preparing / switching / switched / failed / rolled_back / finalized status_revision: integer(int64) active_endpoint: NodeGatewayEndpoint error_code: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/{id}/gateway-port-transitions/{transition_id}
Get the durable communication-port transition state
- operationId
getNodeGatewayPortTransition- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in a platform scope. State is advanced only by status events bound to the node certificate and JetStream PubAck identity.
参数
getNodeGatewayPortTransition 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
transition_id | path | string(uuid) | 是 | — |
|---|
响应
getNodeGatewayPortTransition 响应| 状态码 | 说明 |
|---|
200 | Current durable transition state. 字段：id: string(uuid) scope_id: string(uuid) node_id: string(uuid) revision: integer(int64) expected_node_revision: integer(int64) old_endpoint: NodeGatewayEndpoint new_endpoint: NodeGatewayEndpoint compatibility_deadline: string(date-time) rollback_deadline: string(date-time) state: string: preparing / switching / switched / failed / rolled_back / finalized status_revision: integer(int64) active_endpoint: NodeGatewayEndpoint error_code: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/{id}/gateway-port-transitions/{transition_id}/finalize
Finalize a switched Agent Gateway communication port
- operationId
finalizeNodeGatewayPortTransition- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. Finalization is accepted only after the durable switched state and before the rollback deadline. Reuse both X-Request-ID and Idempotency-Key for an exact retry. A missing, disabled or unavailable command runtime returns 503 node_port_transition_runtime_unavailable without queueing an action. A 202 response confirms acceptance, not listener retirement or completed execution.
参数
finalizeNodeGatewayPortTransition 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
transition_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string(uuid) | 否 | Caller-stable canonical UUID. Send and retain it together with the same Idempotency-Key when retrying an action after an uncertain response. If omitted, the server generates a new ID for each HTTP request and cannot recognize an exact action retry. |
|---|
响应
finalizeNodeGatewayPortTransition 响应| 状态码 | 说明 |
|---|
202 | A durable finalize command was accepted, or the original action was replayed. 字段：id: string(uuid) scope_id: string(uuid) node_id: string(uuid) revision: integer(int64) expected_node_revision: integer(int64) old_endpoint: NodeGatewayEndpoint new_endpoint: NodeGatewayEndpoint compatibility_deadline: string(date-time) rollback_deadline: string(date-time) state: string: preparing / switching / switched / failed / rolled_back / finalized status_revision: integer(int64) active_endpoint: NodeGatewayEndpoint error_code: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/nodes/{id}/gateway-port-transitions/{transition_id}/rollback
Roll back an Agent Gateway communication-port transition
- operationId
rollbackNodeGatewayPortTransition- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.manage in a platform scope. Rollback is accepted only while the previous listener remains inside its versioned rollback window. Reuse both X-Request-ID and Idempotency-Key for an exact retry. A missing, disabled or unavailable command runtime returns 503 node_port_transition_runtime_unavailable without queueing an action. A 202 response confirms acceptance, not completed rollback.
参数
rollbackNodeGatewayPortTransition 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
transition_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string(uuid) | 否 | Caller-stable canonical UUID. Send and retain it together with the same Idempotency-Key when retrying an action after an uncertain response. If omitted, the server generates a new ID for each HTTP request and cannot recognize an exact action retry. |
|---|
响应
rollbackNodeGatewayPortTransition 响应| 状态码 | 说明 |
|---|
202 | A durable rollback command was accepted, or the original action was replayed. 字段：id: string(uuid) scope_id: string(uuid) node_id: string(uuid) revision: integer(int64) expected_node_revision: integer(int64) old_endpoint: NodeGatewayEndpoint new_endpoint: NodeGatewayEndpoint compatibility_deadline: string(date-time) rollback_deadline: string(date-time) state: string: preparing / switching / switched / failed / rolled_back / finalized status_revision: integer(int64) active_endpoint: NodeGatewayEndpoint error_code: string created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/{id}/ip-location
Get a node's IP location (automatic resolution and manual fields)
- operationId
getNodeIPLocation- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in a platform scope. effective 是条件匹配（L2 条件的节点国家代码/运营商/省份/城市、 市场供货分组）实际使用的值；manual_fields 里的字段是管理员修正的，其余来自 resolution（主控 IP 情报库按 IPv4、IPv6、子 IP 的顺序解析出的第一个结果，新增节点、地址变化、IP 库更新后一分钟内重新解析）。 resolution 为 null 表示尚未解析；outcome unresolved 为 IP 库里查不到，no_library 为主控尚无 IP 库。
参数
getNodeIPLocation 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getNodeIPLocation 响应| 状态码 | 说明 |
|---|
200 | Node IP location. 字段：node_id: string(uuid) effective: NodeManagementIPLocation manual_fields: array<string: country / province / city / isp / country_code> resolution: null | object |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/nodes/{id}/metrics/latest
Get the latest durable load sample for one platform node
- operationId
getLatestNodeMetrics- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires nodes.read in a platform scope. The latest row is selected by the accepted publication sequence, not by the Agent clock. puback_sequence is the authoritative JetStream stream sequence returned to the Gateway. Reports from older Agents remain visible with known=false and all six metric values null; unknown values are never represented as zero.
参数
getLatestNodeMetrics 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getLatestNodeMetrics 响应| 状态码 | 说明 |
|---|
200 | Latest accepted metric sample and its durable delivery identity. 字段：record_kind?: string: metric / host_metric telemetry_detail?: boolean storage_supported?: boolean node_id: string(uuid) node_name: string config_revision: integer(int64) active_config_revision: integer(int64) publication_sequence: integer(int64) observed_at: string(date-time) probe_port: integer healthy: boolean probe_succeeded: boolean consecutive_failures: integer consecutive_successes: integer probes_total: integer(int64) probe_failures_total: integer(int64) recovered: boolean recovery_notified: boolean rolled_back: boolean known: boolean cpu_percent: number(double) | null(double) memory_used_bytes: integer(int64) | null(int64) memory_total_bytes: integer(int64) | null(int64) active_connections: integer(int64) | null(int64) rx_bandwidth_bps: integer(int64) | null(int64) tx_bandwidth_bps: integer(int64) | null(int64) total_rx_bytes: integer(int64) | null(int64) total_tx_bytes: integer(int64) | null(int64) telemetry?: NodeTelemetry latest_recovery?: object puback_stream: string puback_sequence: integer(int64) consumer_durable: string consumer_sequence: integer(int64) ingested_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表