Operation details
GET /v1/nodes
List platform nodes with explicit inventory order and keyset pagination
- operationId
listNodes- 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)
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.
Parameters
listNodes Parameters| Name | In | Type | Required | Description |
|---|
status | query | string: pending / active / draining / disabled / retired | No | 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 | No | Effective presence derived from the confirmed PostgreSQL projection and the offline threshold. |
|---|
search | query | string | No | Optional literal node search. Surrounding whitespace is ignored; control characters are rejected. |
|---|
order | query | string: management_sort_desc | No | 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 | No | 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 | No | — |
|---|
Responses
listNodes Responses| Status | Description |
|---|
200 | Node page in the requested order; explicit order is echoed only for the ordered response. |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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/nodes
Create a pending platform node
- operationId
createNode- 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)
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.
Parameters
createNode Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createNode Request body| Name | Type | Required | Description |
|---|
name | string | Yes | — |
|---|
description | string | No | — |
|---|
region | string | No | — |
|---|
ipv4 | string(ipv4) | No | — |
|---|
ipv6 | string(ipv6) | No | — |
|---|
issue_enrollment_token | boolean | No | — |
|---|
enrollment_purpose | string: initial_enrollment / re_enrollment | No | — |
|---|
enrollment_token_ttl_seconds | integer | No | — |
|---|
Responses
createNode Responses| Status | Description |
|---|
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. Fields：node: Node enrollment_token?: IssuedEnrollmentToken |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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/nodes/batch-admin-state
Update one administrative state across a batch of nodes
- operationId
batchUpdateNodeAdminState- 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)
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.
Parameters
batchUpdateNodeAdminState Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
batchUpdateNodeAdminState Request body| Name | Type | Required | Description |
|---|
admin_state | string: active / draining / disabled / retired | Yes | — |
|---|
items | array<BatchNodeAdminStateItem> | Yes | — |
|---|
Responses
batchUpdateNodeAdminState Responses| Status | Description |
|---|
200 | Ordered per-item results. Successful items are committed even when other items fail validation against current state. Fields：items: array<BatchNodeAdminStateItemResult> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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/nodes/installation-tickets
Get each node's last license service ticket and the days left
- operationId
getNodeInstallationTickets- 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)
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.
Parameters
getNodeInstallationTickets Parameters| Name | In | Type | Required | Description |
|---|
node_id | query | array<string(uuid)> | Yes | — |
|---|
Responses
getNodeInstallationTickets Responses| Status | Description |
|---|
200 | One ticket view per requested node. Fields：observed_at: string(date-time) items: array<object> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/metrics/latest
Get latest durable load samples for a bounded set of platform nodes
- operationId
getLatestNodeMetricsBatch- 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)
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.
Parameters
getLatestNodeMetricsBatch Parameters| Name | In | Type | Required | Description |
|---|
node_id | query | array<string(uuid)> | Yes | — |
|---|
Responses
getLatestNodeMetricsBatch Responses| Status | Description |
|---|
200 | Complete scoped batch, with absent samples distinguished from measured values. Fields：observed_at: string(date-time) items: array<NodeMetricsLatest> not_reported_node_ids: array<string(uuid)> |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/monitoring/latest
批量读取节点本机 TCP 探测事实与当前生效策略
- operationId
getLatestNodeMonitoring- 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)
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.
Parameters
getLatestNodeMonitoring Parameters| Name | In | Type | Required | Description |
|---|
node_id | query | array<string(uuid)> | Yes | 1–300 unique canonical lowercase nonzero UUIDs; no other query keys are accepted. |
|---|
Responses
getLatestNodeMonitoring Responses| Status | Description |
|---|
200 | 当前生效配置与实际探测事实；缺失数据保持 null。 Fields：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 |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/registration-credential
Get the reusable node registration credential
- operationId
getNodeRegistrationCredential- 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)
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.
Responses
getNodeRegistrationCredential Responses| Status | Description |
|---|
200 | Current credential. Fields：key_id: string(uuid) credential: string issued_at: string(date-time) |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/nodes/registration-credential/reset
Reset the node registration credential
- operationId
resetNodeRegistrationCredential- 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)
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.
Responses
resetNodeRegistrationCredential Responses| Status | Description |
|---|
200 | New credential. Fields：key_id: string(uuid) credential: string issued_at: string(date-time) |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/{id}
Get one platform node
- operationId
getNode- 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)
Requires nodes.read in a platform scope. platform.admin remains a wildcard permission.
Parameters
getNode Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getNode Responses| Status | Description |
|---|
200 | Node inventory record. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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/nodes/{id}
Update node inventory metadata or administrative state
- operationId
updateNode- 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)
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.
Parameters
updateNode Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
updateNode Request body| Name | Type | Required | Description |
|---|
name | string | No | — |
|---|
description | string | No | — |
|---|
region | string | No | — |
|---|
ipv4 | string(ipv4) | string | No | An IPv4 address, or an empty string to clear the address. |
|---|
ipv6 | string(ipv6) | string | No | An IPv6 address, or an empty string to clear the address. |
|---|
admin_state | string: active / draining / disabled / retired | No | — |
|---|
management_settings | NodeManagementSettings | No | — |
|---|
Responses
updateNode Responses| Status | Description |
|---|
200 | Updated node, or the original response for an identical idempotent replay. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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
POST /v1/nodes/{id}/enrollment-tokens
Issue a one-time enrollment token
- operationId
issueNodeEnrollmentToken- 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)
Requires nodes.manage in a platform scope. platform.admin remains a wildcard permission. The raw token is shown only in this response.
Parameters
issueNodeEnrollmentToken Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
issueNodeEnrollmentToken Request body| Name | Type | Required | Description |
|---|
purpose | string: initial_enrollment / re_enrollment | No | — |
|---|
ttl_seconds | integer | No | — |
|---|
Responses
issueNodeEnrollmentToken Responses| Status | Description |
|---|
201 | Token issued. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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
POST /v1/nodes/{id}/gateway-port-transitions
Start a versioned Agent Gateway communication-port transition
- operationId
createNodeGatewayPortTransition- 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)
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.
Parameters
createNodeGatewayPortTransition Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createNodeGatewayPortTransition Request body| Name | Type | Required | Description |
|---|
expected_node_revision | integer(int64) | Yes | — |
|---|
old_endpoint | NodeGatewayEndpoint | Yes | — |
|---|
new_endpoint | NodeGatewayEndpoint | Yes | — |
|---|
compatibility_deadline | string(date-time) | Yes | — |
|---|
rollback_deadline | string(date-time) | Yes | — |
|---|
Responses
createNodeGatewayPortTransition Responses| Status | Description |
|---|
201 | Transition and durable switch command created, or the original result replayed. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/{id}/gateway-port-transitions/{transition_id}
Get the durable communication-port transition state
- operationId
getNodeGatewayPortTransition- 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)
Requires nodes.read in a platform scope. State is advanced only by status events bound to the node certificate and JetStream PubAck identity.
Parameters
getNodeGatewayPortTransition Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
transition_id | path | string(uuid) | Yes | — |
|---|
Responses
getNodeGatewayPortTransition Responses| Status | Description |
|---|
200 | Current durable transition state. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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
POST /v1/nodes/{id}/gateway-port-transitions/{transition_id}/finalize
Finalize a switched Agent Gateway communication port
- operationId
finalizeNodeGatewayPortTransition- 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)
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.
Parameters
finalizeNodeGatewayPortTransition Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
transition_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string(uuid) | No | 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. |
|---|
Responses
finalizeNodeGatewayPortTransition Responses| Status | Description |
|---|
202 | A durable finalize command was accepted, or the original action was replayed. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/nodes/{id}/gateway-port-transitions/{transition_id}/rollback
Roll back an Agent Gateway communication-port transition
- operationId
rollbackNodeGatewayPortTransition- 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)
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.
Parameters
rollbackNodeGatewayPortTransition Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
transition_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string(uuid) | No | 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. |
|---|
Responses
rollbackNodeGatewayPortTransition Responses| Status | Description |
|---|
202 | A durable rollback command was accepted, or the original action was replayed. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/nodes/{id}/ip-location
Get a node's IP location (automatic resolution and manual fields)
- operationId
getNodeIPLocation- 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)
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 库。
Parameters
getNodeIPLocation Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getNodeIPLocation Responses| Status | Description |
|---|
200 | Node IP location. Fields：node_id: string(uuid) effective: NodeManagementIPLocation manual_fields: array<string: country / province / city / isp / country_code> resolution: null | object |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
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
GET /v1/nodes/{id}/metrics/latest
Get the latest durable load sample for one platform node
- operationId
getLatestNodeMetrics- 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)
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.
Parameters
getLatestNodeMetrics Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getLatestNodeMetrics Responses| Status | Description |
|---|
200 | Latest accepted metric sample and its durable delivery identity. Fields：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 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
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.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list