{ "openapi": "3.1.0", "info": { "title": "NetSeed NSD Customer API", "version": "v1", "description": "Supported NetSeed customer management API." }, "servers": [ { "url": "https://nsd.haiyand.com", "description": "NetSeed testing service" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "身份与用户", "description": "验证令牌上下文，并读取当前 Network 中的用户。" }, { "name": "节点、服务与网关", "description": "读取节点、服务和网关运行信息，并维护允许编辑的服务元数据。" }, { "name": "用户组与访问授权", "description": "维护用户组、组成员和访问授权；写操作需要 `full` 令牌。" }, { "name": "子网路由与运行数据", "description": "读取或维护子网路由，并查询用量和活动日志。" }, { "name": "Webhook API", "description": "维护 Webhook 订阅、发送测试事件，并读取投递结果。" } ], "paths": { "/api/v1/me": { "get": { "tags": [ "身份与用户" ], "summary": "读取当前身份", "operationId": "me", "responses": { "200": { "description": "返回当前用户及所在 Network/Organization 上下文。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/users": { "get": { "tags": [ "身份与用户" ], "summary": "列出用户", "operationId": "list_users", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor — the last id of the previous page. Absent on page 1.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Requested page size; clamped to `1..=MAX_LIMIT`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of users in the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/users/{id}": { "get": { "tags": [ "身份与用户" ], "summary": "读取用户", "operationId": "get_user", "parameters": [ { "name": "id", "in": "path", "description": "User ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such user in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/nodes": { "get": { "tags": [ "节点、服务与网关" ], "summary": "列出节点", "operationId": "list_nodes", "parameters": [ { "name": "kind", "in": "query", "description": "Filter by machine kind (NSN, NSC, NSGW).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "cursor", "in": "query", "description": "Pagination cursor. Use next_cursor from the previous response unchanged.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Cursor pagination: requested page size.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated Node inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListNodesResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/services": { "get": { "tags": [ "节点、服务与网关" ], "summary": "列出服务", "operationId": "list_services", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor — the last id of the previous page. Absent on page 1.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Requested page size; clamped to `1..=MAX_LIMIT`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of services in the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServicesResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/services/{id}": { "get": { "tags": [ "节点、服务与网关" ], "summary": "读取服务", "operationId": "get_service", "parameters": [ { "name": "id", "in": "path", "description": "Service ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The service with public-edge and source-IP overlays", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such service in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "节点、服务与网关" ], "summary": "修改服务元数据", "description": "Body: `{exposed: bool, public_host?: string, subject_policy?: \"external_idp\"|\"anonymous\"}`.\nThis is operator intent that the synthesizer reads instead of anything the\nNSN reports, so it survives the NSN `services_report` replace. An exposed HTTP\nroute requires a `public_host`. Realm-scoped to the caller; a service outside\nthe caller's realm is 404, a `public_host` already claimed is 409.", "operationId": "update_service", "parameters": [ { "name": "id", "in": "path", "description": "Service ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "204": { "description": "Public-edge overlay updated" }, "400": { "description": "Invalid input (e.g. exposed without public_host)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such service in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "public_host already in use by another service", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "节点、服务与网关" ], "summary": "删除服务", "operationId": "delete_service", "parameters": [ { "name": "id", "in": "path", "description": "Service ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteServiceRequest" } } }, "required": true }, "responses": { "200": { "description": "Service retired and service-owned overlays removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteServiceResponse" } } } }, "400": { "description": "Typed confirmation is invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such service in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Service changed or is still referenced", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/gateways": { "get": { "tags": [ "节点、服务与网关" ], "summary": "列出网关", "operationId": "list_gateways", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor — the last id of the previous page. Absent on page 1.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Requested page size; clamped to `1..=MAX_LIMIT`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of gateways visible to the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGatewaysResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/gateways/{id}": { "get": { "tags": [ "节点、服务与网关" ], "summary": "读取网关", "operationId": "get_gateway", "parameters": [ { "name": "id", "in": "path", "description": "Gateway machine ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such gateway in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/groups": { "get": { "tags": [ "用户组与访问授权" ], "summary": "列出用户组", "operationId": "list_groups", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor — the last id of the previous page. Absent on page 1.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Requested page size; clamped to `1..=MAX_LIMIT`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of groups in the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGroupsResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "用户组与访问授权" ], "summary": "创建用户组", "operationId": "create_group", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } }, "required": true }, "responses": { "201": { "description": "Created group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/groups/{id}": { "get": { "tags": [ "用户组与访问授权" ], "summary": "读取用户组", "operationId": "get_group", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The group with member count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "用户组与访问授权" ], "summary": "修改用户组", "operationId": "update_group", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "System group is read-only", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "用户组与访问授权" ], "summary": "删除用户组", "operationId": "delete_group", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Group deleted" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "System group is read-only", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/groups/{id}/members": { "get": { "tags": [ "用户组与访问授权" ], "summary": "列出组成员", "operationId": "list_group_members", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The group's member users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserView" } } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "用户组与访问授权" ], "summary": "添加组成员", "operationId": "add_group_member", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGroupMemberRequest" } } }, "required": true }, "responses": { "200": { "description": "Member added; returns the updated member list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserView" } } } } }, "400": { "description": "Missing user_id, or user is not in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "System group is read-only", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/groups/{id}/members/{user_id}": { "delete": { "tags": [ "用户组与访问授权" ], "summary": "移除组成员", "operationId": "remove_group_member", "parameters": [ { "name": "id", "in": "path", "description": "Group ULID", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "User ULID to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Member removed" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "System group is read-only", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such group in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/policies": { "get": { "tags": [ "用户组与访问授权" ], "summary": "列出访问授权", "operationId": "list_policies", "parameters": [ { "name": "cursor", "in": "query", "description": "Cursor pagination: last policy id returned by the previous page.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Requested page size (clamped by the shared pagination contract).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "q", "in": "query", "description": "Case-insensitive literal substring search over policy name and stable id.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Paginated list of policies in the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPoliciesResponse" } } } }, "400": { "description": "Search query exceeds 128 characters", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "用户组与访问授权" ], "summary": "创建访问授权", "operationId": "create_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } }, "required": true }, "responses": { "201": { "description": "Created policy with distribution summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponse" } } } }, "400": { "description": "Invalid policy subject, or a subject/resource references an object not in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "OIDC provider conflicts with another ACL on the public ingress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/policies/batch": { "post": { "tags": [ "用户组与访问授权" ], "summary": "批量创建访问授权", "operationId": "create_policy_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyBatchRequest" } } }, "required": true }, "responses": { "201": { "description": "Created policies with one distribution update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBatchMutationResponse" } } } }, "400": { "description": "Invalid batch or policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Bulk creation is unavailable when policy approval is required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/policies/{id}": { "get": { "tags": [ "用户组与访问授权" ], "summary": "读取访问授权", "operationId": "get_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyView" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such policy in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "用户组与访问授权" ], "summary": "修改访问授权", "operationId": "update_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated policy with distribution summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponse" } } } }, "400": { "description": "Invalid policy subject, or a subject/resource references an object not in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such policy in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "OIDC provider conflicts with another ACL on the public ingress", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "用户组与访问授权" ], "summary": "删除访问授权", "operationId": "delete_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Policy deleted" }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such policy in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/subnets": { "get": { "tags": [ "子网路由与运行数据" ], "summary": "列出子网路由", "operationId": "list", "responses": { "200": { "description": "Subnet mappings for the caller's Network.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MappingResponse" } } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Subnet mapping authority unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "子网路由与运行数据" ], "summary": "创建或加入子网路由", "operationId": "create_or_join", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrJoinRequest" } } }, "required": true }, "responses": { "201": { "description": "Mapping created, or the caller joined an existing one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MappingResponse" } } } }, "400": { "description": "Malformed IPv4 CIDR, gateway machine id, or subnet id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Gateway is not a member of the caller's Network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Join CIDR does not match the target mapping, or the Network address authority is missing", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Subnet mapping authority unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Address allocation retries exhausted; retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/subnets/{subnet_id}": { "delete": { "tags": [ "子网路由与运行数据" ], "summary": "撤销子网路由", "operationId": "withdraw", "parameters": [ { "name": "subnet_id", "in": "path", "description": "Stable subnet mapping ID.", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "204": { "description": "Mapping withdrawn; its allocation is retained and never reused" }, "400": { "description": "Malformed subnet id", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "No such mapping in the caller's Network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Subnet mapping authority unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/usage": { "get": { "tags": [ "子网路由与运行数据" ], "summary": "读取流量用量", "operationId": "get_usage", "parameters": [ { "name": "from", "in": "query", "description": "Count only reports whose window starts at or after this instant.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "to", "in": "query", "description": "Count only reports whose window ends at or before this instant.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Gateway-metered usage for the caller's realm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReadoutDto" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/audit-events": { "get": { "tags": [ "子网路由与运行数据" ], "summary": "读取活动日志", "operationId": "list_audit_events", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of events to return per page.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Cursor pagination: last id of the previous page. The audit ledger is\ndescending (newest first), so this anchors `id < cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "description": "Server-side time lower bound (unix seconds): keep events with `ts >=`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "outcome", "in": "query", "description": "Server-side exact outcome filter (`success` | `denied` | `error`).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Server-side case-insensitive substring search on action / actor / resource.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Realm-scoped audit events (paginated; supports `outcome` and `q` query filters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditEventsResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhook API" ], "summary": "列出 Webhook", "operationId": "list", "responses": { "200": { "description": "Subscriptions in the caller's realm (secret never returned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhook API" ], "summary": "创建 Webhook", "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } }, "required": true }, "responses": { "201": { "description": "Created subscription (secret sealed, not returned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } } }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhooks/{id}": { "patch": { "tags": [ "Webhook API" ], "summary": "修改 Webhook", "operationId": "update", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } }, "required": true }, "responses": { "200": { "description": "Updated subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionView" } } } }, "404": { "description": "No such subscription in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Webhook API" ], "summary": "删除 Webhook", "operationId": "delete", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "No such subscription in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhook API" ], "summary": "发送测试事件", "operationId": "test_send", "parameters": [ { "name": "id", "in": "path", "description": "Subscription ULID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The destination accepted a synthetic webhook.test event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "404": { "description": "No such subscription in this realm", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "502": { "description": "The destination rejected the event or delivery failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/webhook-deliveries": { "get": { "tags": [ "Webhook API" ], "summary": "读取投递记录", "operationId": "deliveries", "responses": { "200": { "description": "Up to 200 most-recent delivery attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookDeliveriesResponse" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "NSD API token", "description": "Send an opaque nsda_ token in Authorization: Bearer $NSD_TOKEN." } }, "schemas": { "ListWebhookDeliveriesResponse": { "type": "object", "description": "Webhook delivery-log response.", "required": [ "deliveries" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryView" }, "description": "Newest delivery attempts." } } }, "WebhookDeliveryView": { "type": "object", "description": "One webhook delivery-log row.", "required": [ "id", "subscription_id", "event_id", "event_action", "status", "attempts", "created_at" ], "properties": { "attempts": { "type": "integer", "format": "int32", "description": "Attempt count." }, "created_at": { "type": "string", "description": "Creation timestamp." }, "event_action": { "type": "string", "description": "Event action." }, "event_id": { "type": "string", "description": "Event id." }, "id": { "type": "string", "description": "Delivery ULID." }, "last_error": { "type": [ "string", "null" ], "description": "Last delivery error, or `null`." }, "last_status": { "type": [ "integer", "null" ], "format": "int32", "description": "Last HTTP status returned by the destination, or `null`." }, "status": { "type": "string", "description": "Delivery status." }, "subscription_id": { "type": "string", "description": "Subscription ULID." } } }, "WebhookTestResponse": { "type": "object", "description": "Webhook test-send response.", "required": [ "sent" ], "properties": { "sent": { "type": "boolean", "description": "Whether the test event was queued and delivered." } } }, "WebhookSubscriptionView": { "type": "object", "description": "Webhook subscription view. Secrets are never returned.", "required": [ "id", "url", "has_secret", "event_types", "enabled", "description", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "description": "Creation timestamp." }, "description": { "type": "string", "description": "Operator note." }, "enabled": { "type": "boolean", "description": "Whether delivery is enabled." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Action prefixes matched by this subscription. Empty means all events." }, "has_secret": { "type": "boolean", "description": "Whether a sealed HMAC secret exists." }, "id": { "type": "string", "description": "Subscription ULID." }, "updated_at": { "type": "string", "description": "Last update timestamp." }, "url": { "type": "string", "description": "Destination URL." } } }, "WebhookInput": { "type": "object", "description": "Admin create/update body (`secret` write-only).", "required": [ "url" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Free-form operator note." }, "enabled": { "type": "boolean", "description": "Whether the subscription is active." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Action prefixes to match (e.g. `policy.`, `user.create`). Empty = all." }, "secret": { "type": [ "string", "null" ], "description": "HMAC signing secret. Required on create; on update, omit to keep the\ncurrent secret. Write-only — never echoed back.", "writeOnly": true }, "url": { "type": "string", "description": "Destination URL that events are delivered to via HTTP POST (https)." } } }, "ListWebhooksResponse": { "type": "object", "description": "Webhook subscription list response.", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionView" }, "description": "Webhook subscriptions in the caller's realm." } } }, "ListAuditEventsResponse": { "type": "object", "description": "Cursor-paginated audit-event list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEventView" }, "description": "Audit events in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null`." } } }, "AuditEventView": { "type": "object", "description": "Audit event row.", "required": [ "id", "realm_id", "actor_label", "actor_type", "action", "resource_type", "outcome", "ts" ], "properties": { "action": { "type": "string", "description": "Action string." }, "actor_id": { "type": [ "string", "null" ], "description": "Actor id." }, "actor_label": { "type": "string", "description": "Actor label." }, "actor_type": { "type": "string", "description": "Actor type." }, "error_detail": { "type": [ "string", "null" ], "description": "Error detail." }, "id": { "type": "string", "description": "Audit event ULID." }, "ip": { "type": [ "string", "null" ], "description": "Source IP." }, "outcome": { "type": "string", "description": "Outcome." }, "realm_id": { "type": "string", "description": "Realm ULID." }, "resource_id": { "type": [ "string", "null" ], "description": "Resource id." }, "resource_label": { "type": [ "string", "null" ], "description": "Resource label." }, "resource_type": { "type": "string", "description": "Resource type." }, "ts": { "type": "string", "description": "Timestamp." } } }, "UsageReadoutDto": { "type": "object", "description": "`GET /api/v1/usage` response.", "required": [ "realm", "org_id", "total", "by_path" ], "properties": { "by_path": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineDto" }, "description": "Stably ordered by `(path_class, subject_kind, subject_id)`." }, "from": { "type": [ "integer", "null" ], "format": "int64", "description": "Echo of the requested lower bound.", "minimum": 0 }, "org_id": { "type": "string", "description": "Billing org that owns the realm." }, "realm": { "type": "string", "description": "Realm the usage belongs to (the caller's)." }, "to": { "type": [ "integer", "null" ], "format": "int64", "description": "Echo of the requested upper bound.", "minimum": 0 }, "total": { "$ref": "#/components/schemas/UsageTotalsDto", "description": "Summed across every line in `by_path`." } } }, "UsageTotalsDto": { "type": "object", "description": "Realm totals. Decimal strings — see the module note.", "required": [ "rx_bytes", "tx_bytes" ], "properties": { "rx_bytes": { "type": "string", "description": "Total bytes client → gateway." }, "tx_bytes": { "type": "string", "description": "Total bytes gateway → client." } } }, "UsageLineDto": { "type": "object", "description": "One `(path_class, subject)` line of the breakdown.", "required": [ "path_class", "rx_bytes", "tx_bytes" ], "properties": { "connections_opened": { "type": [ "integer", "null" ], "format": "int64", "description": "Connections opened, summed. Telemetry, never billed.", "minimum": 0 }, "connections_peak": { "type": [ "integer", "null" ], "format": "int64", "description": "**Peak** concurrent connections — the `MAX`, never a sum.", "minimum": 0 }, "path_class": { "type": "string", "description": "`terminate` | `wg_relay` | `wss_relay` | `gateway_egress` | `gateway_exit`\n| `public_edge`." }, "rx_bytes": { "type": "string", "description": "Bytes client → gateway, summed." }, "subject_id": { "type": [ "string", "null" ], "description": "The machine or user id. Absent on a realm aggregate." }, "subject_kind": { "type": [ "string", "null" ], "description": "`machine` | `user`. Absent on a realm aggregate." }, "tx_bytes": { "type": "string", "description": "Bytes gateway → client, summed." } } }, "CreateOrJoinRequest": { "type": "object", "description": "One create request, or an explicit standby join when `join_subnet_id` is set.", "required": [ "real_cidr", "gateway_machine_id" ], "properties": { "gateway_machine_id": { "type": "string", "description": "Registered gateway machine that publishes this mapping." }, "join_subnet_id": { "type": [ "integer", "null" ], "format": "int32", "description": "Existing mapping to join; omitted creates an independent mapping.", "minimum": 0 }, "real_cidr": { "type": "string", "description": "Real IPv4 LAN CIDR. Host bits are normalized to the network address." } } }, "MappingResponse": { "type": "object", "description": "A subnet mapping and the nodes currently providing its high-availability routing.", "required": [ "subnet_id", "display_label", "real_cidr", "mapped_prefix", "generation", "standby_gateway_machine_ids", "selection_generation", "withdrawn" ], "properties": { "active_gateway_machine_id": { "type": [ "string", "null" ], "description": "Gateway currently publishing the mapping, absent while none is healthy." }, "display_label": { "type": "string", "description": "Operator-facing label derived from the mapping." }, "generation": { "type": "integer", "format": "int64", "description": "Mapping revision; advances when the mapping itself changes.", "minimum": 0 }, "mapped_prefix": { "type": "string", "description": "Overlay prefix this LAN is reachable at inside the Network." }, "real_cidr": { "type": "string", "description": "Real IPv4 LAN CIDR, normalized to the network address." }, "selection_generation": { "type": "integer", "format": "int64", "description": "Active-gateway selection revision; advances on every failover.", "minimum": 0 }, "standby_gateway_machine_ids": { "type": "array", "items": { "type": "string" }, "description": "Gateways that have joined the mapping and can take over." }, "subnet_id": { "type": "integer", "format": "int32", "description": "Stable subnet mapping ID within the Network.", "minimum": 0 }, "withdrawn": { "type": "boolean", "description": "Whether the mapping was withdrawn. Its allocation is retained and never\nreused, so a withdrawn mapping still occupies its prefix." } } }, "UpdatePolicyRequest": { "type": "object", "description": "`PATCH /api/v1/policies/{id}` request body. Omitted fields are left unchanged.", "properties": { "conditions": { "type": "object", "description": "New conditions object." }, "enabled": { "type": [ "boolean", "null" ], "description": "Enable/disable the policy." }, "enforced_at": { "type": [ "string", "null" ], "description": "Deprecated compatibility hint. NSD preserves an unchanged legacy\npolicy shape or derives the enforcement point after a shape change." }, "name": { "type": [ "string", "null" ], "description": "New display name." }, "resource": { "type": "object", "description": "New resource object." }, "subject": { "type": "object", "description": "New subject object." } } }, "PolicyView": { "type": "object", "description": "Access grant. Fields in subject, resource and conditions depend on their type; an oidc_org subject includes provider_ref and organization_id.", "required": [ "id", "realm_id", "name", "subject", "resource", "action", "enabled", "conditions", "version", "created_at", "created_by", "enforced_at", "compile_status" ], "properties": { "action": { "type": "string", "description": "Effect (currently always `allow`)." }, "compile_error": { "type": [ "string", "null" ], "description": "Why the Grant is dropped. Absent while `compile_status` is `compiled`." }, "compile_error_code": { "type": [ "string", "null" ], "description": "Stable token naming the same rejection as `compile_error`, for alerting\nthat must not depend on wording. Absent while `compile_status` is\n`compiled`." }, "compile_status": { "$ref": "#/components/schemas/PolicyCompileStatusView", "description": "Whether the grant can take effect. A rejected grant does not allow access even when enabled is true; inspect compile_error and compile_error_code." }, "conditions": { "type": "object", "description": "Free-form conditions object." }, "created_at": { "type": "string", "description": "Creation time (RFC 3339 UTC)." }, "created_by": { "type": "string", "description": "Label of the actor who created it." }, "enabled": { "type": "boolean", "description": "Whether the policy is active." }, "enforced_at": { "type": "string", "description": "Enforcement point (`node` | `gateway`)." }, "id": { "type": "string", "description": "Policy ULID." }, "name": { "type": "string", "description": "Display name." }, "realm_id": { "type": "string", "description": "Owning realm ULID." }, "resource": { "type": "object", "description": "What the policy grants access to (`{ type, … }`)." }, "subject": { "type": "object", "description": "Who the policy applies to (`{ type, … }`)." }, "version": { "type": "integer", "format": "int32", "description": "Monotonic version, bumped on each update." } } }, "PolicyCompileStatusView": { "type": "string", "description": "Grant validation status: compiled means the grant can take effect; rejected means it cannot.", "enum": [ "compiled", "rejected" ] }, "PolicyBatchMutationResponse": { "type": "object", "description": "Atomic bulk-create response.", "required": [ "policies", "distribution" ], "properties": { "distribution": { "$ref": "#/components/schemas/DistributionSummary", "description": "Config-distribution summary for the realm." }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyView" }, "description": "Policies created by the transaction." } } }, "DistributionSummary": { "type": "object", "description": "Distribution summary returned alongside a site mutation.", "required": [ "gateways", "sites", "failed" ], "properties": { "failed": { "type": "integer", "description": "Distribution failures (always 0 in the in-process path today).", "minimum": 0 }, "gateways": { "type": "integer", "description": "Gateways in the realm config was (re)distributed to.", "minimum": 0 }, "sites": { "type": "integer", "description": "Sites in the realm.", "minimum": 0 } } }, "CreatePolicyBatchRequest": { "type": "object", "description": "Atomic bulk-create request used by the ACL editor.", "required": [ "policies" ], "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/CreatePolicyRequest" }, "description": "Complete policy rows to create (2–100)." } } }, "CreatePolicyRequest": { "type": "object", "description": "`POST /api/v1/policies` request body.", "required": [ "name" ], "properties": { "conditions": { "type": "object", "description": "Free-form conditions object." }, "enabled": { "type": [ "boolean", "null" ], "description": "Whether the policy starts enabled (defaults to true)." }, "enforced_at": { "type": [ "string", "null" ], "description": "Deprecated compatibility hint. NSD derives the enforcement point from\nthe policy subject and rejects a conflicting value." }, "name": { "type": "string", "description": "Display name." }, "resource": { "type": "object", "description": "Resource object `{ type, … }` (defaults to \"Everything\")." }, "subject": { "type": "object", "description": "Subject object `{ type, … }` (defaults to \"Everyone\")." } } }, "PolicyMutationResponse": { "type": "object", "description": "`POST`/`PATCH /api/v1/policies` response: the policy plus a distribution summary.", "required": [ "policy", "distribution" ], "properties": { "distribution": { "$ref": "#/components/schemas/DistributionSummary", "description": "Config-distribution summary for the realm." }, "policy": { "$ref": "#/components/schemas/PolicyView", "description": "The created/updated policy." } } }, "ListPoliciesResponse": { "type": "object", "description": "Cursor-paginated policy list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyView" }, "description": "Policies in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there is no next page." } } }, "AddGroupMemberRequest": { "type": "object", "description": "`POST /api/v1/groups/{id}/members` request body.", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "User ULID to add." } } }, "UpdateGroupRequest": { "type": "object", "description": "`PATCH /api/v1/groups/{id}` request body.", "properties": { "description": { "type": [ "string", "null" ], "description": "New description, or `null` to clear." }, "name": { "type": [ "string", "null" ], "description": "New display name." } } }, "GroupView": { "type": "object", "description": "Group row returned by the admin group API.", "required": [ "id", "realm_id", "name", "slug", "kind", "created_at", "created_by", "member_count" ], "properties": { "auto_members": { "type": [ "string", "null" ], "description": "Automatic membership rule for system groups, or `null`." }, "created_at": { "type": "string", "description": "Creation timestamp (RFC 3339 UTC)." }, "created_by": { "type": "string", "description": "Actor label that created the group." }, "description": { "type": [ "string", "null" ], "description": "Optional description." }, "id": { "type": "string", "description": "Group ULID." }, "kind": { "type": "string", "description": "Group kind (`static` or `system`)." }, "member_count": { "type": "integer", "description": "Effective member count.", "minimum": 0 }, "name": { "type": "string", "description": "Display name." }, "realm_id": { "type": "string", "description": "Owning realm ULID." }, "slug": { "type": "string", "description": "URL-safe slug." } } }, "CreateGroupRequest": { "type": "object", "description": "`POST /api/v1/groups` request body.", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description." }, "name": { "type": "string", "description": "Display name." } } }, "ListGroupsResponse": { "type": "object", "description": "Cursor-paginated group list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GroupView" }, "description": "Groups in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there is no next page." } } }, "GatewayView": { "type": "object", "description": "Gateway view returned by tenant gateway APIs.", "required": [ "id", "realm_id", "kind", "name", "pubkey_ed25519", "registered_at", "tags", "endpoint", "operator", "transports", "connections", "latency_p99", "health_check_path", "max_connections", "drained", "peer_key_pub" ], "properties": { "addr": { "type": [ "string", "null" ], "description": "Tunnel address." }, "arch": { "type": [ "string", "null" ], "description": "CPU architecture." }, "connections": { "type": "integer", "format": "int32", "description": "Reported connections." }, "drained": { "type": "boolean", "description": "Whether gateway is drained." }, "endpoint": { "type": "string", "description": "Preferred endpoint." }, "envoy_http_public_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Public HTTP port." }, "health_check_path": { "type": "string", "description": "Health-check path." }, "id": { "type": "string", "description": "Gateway ULID." }, "kind": { "type": "string", "description": "Kind, always `NSGW`." }, "last_seen": { "type": [ "string", "null" ], "description": "Last heartbeat timestamp." }, "latency_p99": { "type": "integer", "format": "int32", "description": "Placeholder p99 latency." }, "max_connections": { "type": "integer", "format": "int32", "description": "Max configured connections." }, "name": { "type": "string", "description": "Gateway name." }, "operator": { "type": "string", "description": "Operator label." }, "os": { "type": [ "string", "null" ], "description": "Operating system." }, "owner_user_id": { "type": [ "string", "null" ], "description": "Owner user ULID." }, "peer_key_pub": { "type": "string", "description": "Peer public key." }, "pubkey_ed25519": { "type": "string", "description": "Machine public key." }, "public_edge": { "type": [ "boolean", "null" ], "description": "Whether this gateway can serve public HTTP edge." }, "public_edge_l4": { "type": [ "boolean", "null" ], "description": "Whether this gateway can serve public L4 edge." }, "realm_id": { "type": "string", "description": "Realm ULID." }, "region": { "type": [ "string", "null" ], "description": "Region." }, "registered_at": { "type": "string", "description": "Registration timestamp." }, "shared": { "type": [ "boolean", "null" ], "description": "Whether this gateway is shared into the viewer realm." }, "site_id": { "type": [ "string", "null" ], "description": "Site ULID." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags." }, "transport": { "type": [ "string", "null" ], "description": "Primary transport." }, "transports": { "type": "array", "items": { "type": "string" }, "description": "Available transports." }, "tunnel_ip": { "type": [ "string", "null" ], "description": "Tunnel IP." }, "version": { "type": [ "string", "null" ], "description": "Reported version." }, "wg_endpoint": { "type": [ "string", "null" ], "description": "`WireGuard` endpoint." }, "wss_endpoint": { "type": [ "string", "null" ], "description": "WSS endpoint." }, "wss_relay": { "type": [ "string", "null" ], "description": "WSS relay URL on detail responses." } } }, "ListGatewaysResponse": { "type": "object", "description": "Cursor-paginated gateway list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayView" }, "description": "Gateways in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null`." } } }, "DeleteServiceResponse": { "type": "object", "description": "Successful service retirement response.", "required": [ "deleted", "summary" ], "properties": { "deleted": { "type": "boolean", "description": "Always true on success." }, "summary": { "$ref": "#/components/schemas/ServiceRetirementSummaryView", "description": "Removed-row summary." } } }, "ServiceRetirementSummaryView": { "type": "object", "description": "Summary of rows removed by one successful service retirement.", "required": [ "service_id", "service_name", "public_edge_rows", "identity_import_rows", "source_ip_rows", "overlay_virtual_port_rows" ], "properties": { "identity_import_rows": { "type": "integer", "description": "Number of identity-import rows removed.", "minimum": 0 }, "overlay_virtual_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Released overlay port, if any.", "minimum": 0 }, "overlay_virtual_port_rows": { "type": "integer", "description": "Number of overlay virtual-port rows removed.", "minimum": 0 }, "public_edge_rows": { "type": "integer", "description": "Number of inactive public-edge rows removed.", "minimum": 0 }, "public_virtual_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Released public listener port, if any.", "minimum": 0 }, "service_id": { "type": "string", "description": "Retired service ULID." }, "service_name": { "type": "string", "description": "Retired service name." }, "source_ip_rows": { "type": "integer", "description": "Number of source-IP rows removed.", "minimum": 0 } } }, "DeleteServiceRequest": { "type": "object", "description": "Typed confirmation and optimistic-concurrency token for service retirement.", "required": [ "confirmation", "expected_updated_at" ], "properties": { "confirmation": { "type": "string", "description": "Must equal `DELETE ` from the latest impact preview." }, "expected_updated_at": { "type": "string", "description": "Exact service update timestamp returned by the latest impact preview." } } }, "ServiceView": { "type": "object", "description": "Service row returned by the admin service catalogue.", "required": [ "id", "name", "protocol", "backend_hint", "vip", "domain", "public_edge", "reported_by", "last_sync_at", "status" ], "properties": { "backend_hint": { "type": "string", "description": "Backend host:port hint." }, "backend_public_edge_ready": { "type": [ "boolean", "null" ], "description": "Whether the backend node can serve as a public-ingress backend." }, "custom_domain": { "type": [ "string", "null" ], "description": "Operator-declared custom domain (`Service.domain` in the node's\n`services.toml`), absent when the service declares none.\n\nFor an HTTP/HTTPS service this is the only host the origin answers on:\nit selects its virtual host by `Host`/SNI and holds a certificate for\nthis name alone, so the FQID lands on the default virtual host instead.\nConsumers presenting an access address must prefer this and fall back to\nthe FQID; the FQID remains the service's identity." }, "domain": { "type": "string", "description": "Service domain: the declared custom domain, or a generated fallback. Read custom_domain to distinguish a declared name." }, "gateway_binding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GatewayBindingView", "description": "Gateway binding, or `null` when unbound." } ] }, "id": { "type": "string", "description": "Service ULID." }, "last_sync_at": { "type": "string", "description": "Last sync time (RFC 3339 UTC)." }, "listen_hint": { "type": [ "string", "null" ], "description": "Optional listen hint." }, "name": { "type": "string", "description": "Service name." }, "protocol": { "type": "string", "description": "Protocol (`tcp`, `udp`, or `http`)." }, "public_edge": { "$ref": "#/components/schemas/ServicePublicEdgeView", "description": "Public ingress overlay." }, "public_virtual_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Public-edge L4 listener port, when configured.", "minimum": 0 }, "reported_by": { "type": "string", "description": "Reporting machine id." }, "short_dns_canonical_name": { "type": [ "string", "null" ], "description": "Short DNS v2 canonical Service FQDN, when compact authority is available." }, "site_id": { "type": [ "string", "null" ], "description": "Site ULID, or `null` when the reporting machine has no site." }, "source_ip": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SourceIpAdmissionView", "description": "Source-IP admission policy, or `null` when unset." } ] }, "status": { "type": "string", "description": "Service status (`active` or `offline`)." }, "vip": { "type": "string", "description": "Backend VIP/host." }, "virtual_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Overlay virtual port used for ACL authoring.", "minimum": 0 } } }, "SourceIpAdmissionView": { "type": "object", "description": "Source-IP admission policy attached to a route.", "required": [ "allow_cidrs", "deny_cidrs", "fail_closed" ], "properties": { "allow_cidrs": { "type": "array", "items": { "type": "string" }, "description": "Allowed CIDR ranges." }, "deny_cidrs": { "type": "array", "items": { "type": "string" }, "description": "Denied CIDR ranges." }, "fail_closed": { "type": "boolean", "description": "Whether the route fails closed when the filter cannot be evaluated." } } }, "ServicePublicEdgeView": { "type": "object", "description": "Public ingress overlay shown on a service.", "required": [ "exposed" ], "properties": { "exposed": { "type": "boolean", "description": "Whether the service is exposed on the public edge." }, "public_host": { "type": [ "string", "null" ], "description": "Public host, or `null` when not exposed." }, "routing_gateway_id": { "type": [ "string", "null" ], "description": "Gateway used for public routing, when pinned." }, "subject_policy": { "type": [ "object", "null" ], "description": "Subject policy selected for the exposure." } } }, "GatewayBindingView": { "type": "object", "description": "Auto or explicit gateway binding shown on a service.", "required": [ "id", "service_id", "gateway_id", "mode", "priority", "auto_bound" ], "properties": { "auto_bound": { "type": "boolean", "description": "Whether this binding is derived from the site's default gateway." }, "gateway_id": { "type": "string", "description": "Gateway ULID." }, "id": { "type": "string", "description": "Binding identifier." }, "mode": { "type": "string", "description": "Transport mode." }, "priority": { "type": "integer", "format": "int32", "description": "Binding priority." }, "service_id": { "type": "string", "description": "Service ULID." } } }, "ListServicesResponse": { "type": "object", "description": "Cursor-paginated service list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceView" }, "description": "Services in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there is no next page." } } }, "ListNodesResponse": { "type": "object", "description": "Cursor-paginated Node inventory response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NodeInventoryView" }, "description": "Nodes in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there is no next page." } } }, "NodeInventoryView": { "type": "object", "description": "Network-scoped Node identity projected from the proven Machine authority.", "required": [ "id", "device_id", "node_id", "name", "device_name", "principal_kind", "node_domain", "runtime_state", "posture_available" ], "properties": { "arch": { "type": [ "string", "null" ], "description": "CPU architecture reported by the associated Device." }, "client_version": { "type": [ "string", "null" ], "description": "NS client version reported by the associated Device." }, "device_id": { "type": "string", "description": "Stable Device identity associated with this Node." }, "device_name": { "type": "string", "description": "Label of the associated Device." }, "hostname": { "type": [ "string", "null" ], "description": "Hostname reported by the associated Device." }, "id": { "type": "string", "description": "NSD record id used by management actions." }, "last_seen": { "type": [ "string", "null" ], "description": "Latest observation time in RFC 3339 UTC, or `null` when never observed." }, "name": { "type": "string", "description": "Operator-facing Node label, or Node identity when unnamed." }, "node_domain": { "type": "string", "description": "Legacy Node DNS name in the configured `node` namespace." }, "node_id": { "type": "string", "description": "Stable Node identity." }, "node_ip": { "type": [ "string", "null" ], "description": "Stable overlay address in this Network." }, "os": { "type": [ "string", "null" ], "description": "Runtime metadata useful for fleet diagnosis." }, "os_version": { "type": [ "string", "null" ], "description": "Operating-system version reported by the associated Device." }, "policy_version": { "type": [ "integer", "null" ], "format": "int64", "description": "Last policy version acknowledged by the Node." }, "posture_available": { "type": "boolean", "description": "Whether the posture authority was readable for this response." }, "principal_kind": { "type": "string", "description": "`user` or `organization`." }, "principal_user_id": { "type": [ "string", "null" ], "description": "Human principal or `null` for an Organization-owned workload." }, "runtime_state": { "type": "string", "description": "`connected`, `offline`, or `waiting_first_connection`." }, "short_dns_canonical_name": { "type": [ "string", "null" ], "description": "Short DNS v2 canonical Node FQDN, when compact authority is available." } } }, "AdminUserView": { "type": "object", "description": "User row returned by the admin user API.", "required": [ "id", "realm_id", "email", "name", "role", "mfa_enabled", "created_at", "disabled" ], "properties": { "created_at": { "type": "string", "description": "Creation timestamp (RFC 3339 UTC)." }, "disabled": { "type": "boolean", "description": "Whether the user is disabled." }, "email": { "type": "string", "description": "Email address." }, "id": { "type": "string", "description": "User ULID." }, "last_login_at": { "type": [ "string", "null" ], "description": "Last login timestamp (RFC 3339 UTC), or `null`." }, "mfa_enabled": { "type": "boolean", "description": "Whether MFA is enabled." }, "name": { "type": "string", "description": "Display name." }, "realm_id": { "type": "string", "description": "Owning realm ULID." }, "role": { "type": "string", "description": "Role (`admin` or `member`)." } } }, "ListUsersResponse": { "type": "object", "description": "Cursor-paginated user list response.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserView" }, "description": "Users in this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there is no next page." } } }, "UserApiView": { "type": "object", "description": "User profile returned by the management API. Does not include passwords or password hashes.", "required": [ "id", "realm_id", "email", "name", "role", "mfa_enabled", "created_at", "disabled" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339 UTC)." }, "disabled": { "type": "boolean", "description": "When `true`, the user cannot authenticate." }, "email": { "type": "string", "description": "`User::email`." }, "id": { "type": "string", "description": "`User::id`, ULID as string." }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful login, if any (RFC 3339 UTC)." }, "mfa_enabled": { "type": "boolean", "description": "MFA opt-in." }, "name": { "type": "string", "description": "`User::name`." }, "oidc_sub": { "type": [ "string", "null" ], "description": "OIDC subject; `None` for local-password users." }, "realm_id": { "type": "string", "description": "`User::realm_id`, ULID as string." }, "role": { "$ref": "#/components/schemas/UserRole", "description": "`User::role`." } } }, "UserRole": { "type": "string", "description": "User role within a realm. Mirrors the `users.role` CHECK constraint.", "enum": [ "admin", "member" ] }, "MeResponse": { "type": "object", "description": "当前登录用户，以及所在 Network 和 Organization 的上下文。", "required": [ "id", "realm_id", "email", "name", "role", "mfa_enabled", "created_at", "disabled", "realm_slug", "realm_name", "realm_created_at", "org_plan" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Row creation timestamp (RFC 3339 UTC)." }, "disabled": { "type": "boolean", "description": "When `true`, the user cannot authenticate." }, "email": { "type": "string", "description": "`User::email`." }, "id": { "type": "string", "description": "`User::id`, ULID as string." }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful login, if any (RFC 3339 UTC)." }, "mfa_enabled": { "type": "boolean", "description": "MFA opt-in." }, "name": { "type": "string", "description": "`User::name`." }, "oidc_sub": { "type": [ "string", "null" ], "description": "OIDC subject; `None` for local-password users." }, "realm_id": { "type": "string", "description": "`User::realm_id`, ULID as string." }, "role": { "$ref": "#/components/schemas/UserRole", "description": "`User::role`." }, "realm_slug": { "type": [ "string", "null" ], "description": "当前 Network 的可读标识；无法读取时为 null。" }, "realm_name": { "type": [ "string", "null" ], "description": "当前 Network 的显示名称；无法读取时为 null。" }, "realm_created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "当前 Network 的创建时间；无法读取时为 null。" }, "org_plan": { "type": [ "string", "null" ], "description": "当前 Organization 的套餐标识；无法读取时为 null。" } } }, "ProblemDetails": { "type": "object", "description": "RFC 7807 error body with a stable NSD error code.", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable problem-type URI." }, "title": { "type": "string", "description": "Short error category." }, "status": { "type": "integer", "description": "HTTP status code." }, "detail": { "type": "string", "description": "Actionable explanation for this occurrence." }, "instance": { "type": [ "string", "null" ], "description": "Request path when available." }, "code": { "type": "string", "description": "Stable dot-namespaced machine-readable code." } } } } } }