PPanel Edge节点协议端点
由 node-protocol.openapi.json 自动生成的 6 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: 29222cd7d92c53089974b05e057674f175d23019dd92bdf391abb29f113c99e4
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/node/config
GET /api/v1/node/config
Desired configuration: runtime, inbounds with secrets, certificates (ETag = hash)
{
"parameters": [
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
},
{
"description": "The ETag last received, verbatim (weak comparison: `W/\"…\"` matches too)",
"in": "header",
"name": "if-none-match",
"required": false,
"schema": {
"description": "The ETag last received, verbatim (weak comparison: `W/\"…\"` matches too)",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeConfig"
}
}
},
"description": "The desired configuration (ETag: \"<hash>\", Cache-Control: no-store)"
},
"304": {
"description": "Unchanged since the ETag sent in If-None-Match (the response carries the ETag)"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.auth_invalid: missing, malformed, unknown or expired agent token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.disabled: agent disabled or server retired"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported: missing or unsupported Node-Protocol (Upgrade: Node-Protocol/1)"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited (Retry-After): per-server limits,"
}
},
"security": [
{
"AgentToken": []
}
],
"summary": "Desired configuration: runtime, inbounds with secrets, certificates (ETag = hash)",
"tags": [
"node-protocol"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": [
{
"AgentToken": []
}
]
}POST /api/v1/node/enroll
POST /api/v1/node/enroll
Exchange the one-time enrollment token for the agent token (retry-safe by enrollment_id)
{
"parameters": [
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeEnrollRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeEnrollResponse"
}
}
},
"description": "Enrolled; a retry with the same enrollment_id within 10 minutes gets the same body"
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.bad_request: unparsable JSON or gzip"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.enrollment_invalid: unknown, used, expired, or the server is retired"
},
"413": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.payload_too_large: more than 1 MiB after decompression"
},
"415": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.unsupported_media_type: not application/json, or a Content-Encoding other than gzip"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.payload_invalid: schema violation, with errors[]"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited: per client address; or the first attempt is still running (Retry-After)"
}
},
"summary": "Exchange the one-time enrollment token for the agent token (retry-safe by enrollment_id)",
"tags": [
"node-protocol"
],
"x-audit": "network.agent.enroll",
"x-body": "json",
"x-body-encoding": "gzip",
"x-body-limit": 1048576,
"x-idempotency": "none",
"x-rate-limit": "node.enroll.ip",
"effectiveSecurity": []
}POST /api/v1/node/heartbeat
POST /api/v1/node/heartbeat
Program, applied configuration and per-inbound results, load, NIC traffic, public addresses
{
"parameters": [
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeHeartbeatRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeHeartbeatResponse"
}
}
},
"description": "Server time, desired revision, next_batch_seq, intervals, notices, credentials"
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.bad_request: unparsable JSON or gzip"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.auth_invalid: missing, malformed, unknown or expired agent token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.disabled: agent disabled or server retired"
},
"413": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.payload_too_large: more than 1 MiB after decompression"
},
"415": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.unsupported_media_type: not application/json, or a Content-Encoding other than gzip"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.payload_invalid: schema violation, with errors[]"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported: missing or unsupported Node-Protocol (Upgrade: Node-Protocol/1)"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited (Retry-After): per-server limits,"
}
},
"security": [
{
"AgentToken": []
}
],
"summary": "Program, applied configuration and per-inbound results, load, NIC traffic, public addresses",
"tags": [
"node-protocol"
],
"x-body": "json",
"x-body-encoding": "gzip",
"x-body-limit": 1048576,
"x-idempotency": "none",
"effectiveSecurity": [
{
"AgentToken": []
}
]
}POST /api/v1/node/online
POST /api/v1/node/online
Online address window and global device-limit decisions
{
"parameters": [
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeOnlineRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeOnlineResponse"
}
}
},
"description": "Recorded users, over-limit users and per-user rejections"
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.bad_request: unparsable JSON or gzip"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.auth_invalid: missing, malformed, unknown or expired agent token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.disabled: agent disabled or server retired"
},
"413": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.payload_too_large: more than 1 MiB after decompression"
},
"415": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.unsupported_media_type: not application/json, or a Content-Encoding other than gzip"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.payload_invalid: schema violation, with errors[]"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported: missing or unsupported Node-Protocol (Upgrade: Node-Protocol/1)"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited (Retry-After): per-server limits,"
}
},
"security": [
{
"AgentToken": []
}
],
"summary": "Online address window and global device-limit decisions",
"tags": [
"node-protocol"
],
"x-body": "json",
"x-body-encoding": "gzip",
"x-body-limit": 1048576,
"x-idempotency": "none",
"effectiveSecurity": [
{
"AgentToken": []
}
]
}POST /api/v1/node/usage
POST /api/v1/node/usage
Idempotent incremental usage batch
{
"parameters": [
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeUsageRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeUsageResponse"
}
}
},
"description": "Accepted, replayed or stale batch"
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.bad_request: unparsable JSON or gzip"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.auth_invalid: missing, malformed, unknown or expired agent token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.disabled: agent disabled or server retired"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.batch_conflict"
},
"413": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.payload_too_large: more than 1 MiB after decompression"
},
"415": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.unsupported_media_type: not application/json, or a Content-Encoding other than gzip"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.payload_invalid: schema violation, with errors[]"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported: missing or unsupported Node-Protocol (Upgrade: Node-Protocol/1)"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited (Retry-After): per-server limits,"
}
},
"security": [
{
"AgentToken": []
}
],
"summary": "Idempotent incremental usage batch",
"tags": [
"node-protocol"
],
"x-body": "json",
"x-body-encoding": "gzip",
"x-body-limit": 1048576,
"x-idempotency": "none",
"effectiveSecurity": [
{
"AgentToken": []
}
]
}GET /api/v1/node/users
GET /api/v1/node/users
Users per inbound with credentials, limits and blocked addresses (ETag = access_version)
{
"parameters": [
{
"in": "query",
"name": "since",
"required": false,
"schema": {
"pattern": "^(0|[1-9][0-9]{0,15})$",
"type": "string"
}
},
{
"description": "Protocol major version: `1`",
"in": "header",
"name": "node-protocol",
"required": true,
"schema": {
"description": "Protocol major version: `1`",
"example": "1",
"type": "string"
}
},
{
"description": "The ETag last received, verbatim (weak comparison: `W/\"…\"` matches too)",
"in": "header",
"name": "if-none-match",
"required": false,
"schema": {
"description": "The ETag last received, verbatim (weak comparison: `W/\"…\"` matches too)",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NodeUsers"
}
}
},
"description": "The user list (ETag: \"<access_version>\", Cache-Control: no-store)"
},
"304": {
"description": "Unchanged since the ETag sent in If-None-Match (the response carries the ETag)"
},
"401": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.auth_invalid: missing, malformed, unknown or expired agent token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.disabled: agent disabled or server retired"
},
"426": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "node.protocol_unsupported: missing or unsupported Node-Protocol (Upgrade: Node-Protocol/1)"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.rate_limited (Retry-After): per-server limits,"
}
},
"security": [
{
"AgentToken": []
}
],
"summary": "Users per inbound with credentials, limits and blocked addresses (ETag = access_version)",
"tags": [
"node-protocol"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": [
{
"AgentToken": []
}
]
}