PPanel Edgeusage
由 openapi.json 自动生成的 13 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
PUT /api/v1/admin/subscriptions/{id}/device-counting-policy
PUT /api/v1/admin/subscriptions/{id}/device-counting-policy
Change IP/HWID counting policy
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"mode": {
"enum": [
"ip",
"hwid",
"both"
],
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HardwareDevicePolicy"
}
}
},
"description": "Policy",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current)"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid policy"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Change IP/HWID counting policy",
"tags": [
"usage"
],
"x-audit": "usage.device.policy",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/admin/subscriptions/{id}/devices
GET /api/v1/admin/subscriptions/{id}/devices
Online devices (masked addresses)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageDevices"
}
}
},
"description": "Success"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Online devices (masked addresses)",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "subscription.subscription.read",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/devices/{deviceKey}/kick
POST /api/v1/admin/subscriptions/{id}/devices/{deviceKey}/kick
Block a device for 30 minutes
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "deviceKey",
"required": true,
"schema": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
}
},
{
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageKickedDevice"
}
}
},
"description": "Success"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Block a device for 30 minutes",
"tags": [
"usage"
],
"x-audit": "usage.device.kick",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "subscription.subscription.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/subscriptions/{id}/hardware-devices
GET /api/v1/admin/subscriptions/{id}/hardware-devices
Hardware device policy and masked observations
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HardwareDevices"
}
}
},
"description": "Devices",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "Hardware device policy and masked observations",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "subscription.subscription.read",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/hardware-devices/{deviceKey}/revoke
POST /api/v1/admin/subscriptions/{id}/hardware-devices/{deviceKey}/revoke
Revoke a hardware hint for 30 minutes
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "deviceKey",
"required": true,
"schema": {
"pattern": "^v[1-9]\\d*\\.[0-9a-f]{64}$",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"revoked_until": {
"format": "date-time",
"type": "string"
}
},
"required": [
"revoked_until"
],
"type": "object"
}
}
},
"description": "Revocation"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such device"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid device"
}
},
"summary": "Revoke a hardware hint for 30 minutes",
"tags": [
"usage"
],
"x-audit": "usage.device.revoke",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/admin/usage/rankings
GET /api/v1/admin/usage/rankings
Daily traffic rankings
{
"parameters": [
{
"in": "query",
"name": "date",
"required": true,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "by",
"required": true,
"schema": {
"enum": [
"subscription",
"server"
],
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"maxLength": 200,
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageRankings"
}
}
},
"description": "Success"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Daily traffic rankings",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "usage.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/usage/reconciliations
GET /api/v1/admin/usage/reconciliations
Usage reconciliation reports with evidence gaps and exception links
{
"parameters": [
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"report": {
"$ref": "#/components/schemas/UsageReconciliationReport"
}
},
"required": [
"id",
"created_at",
"report"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"has_more",
"next_cursor"
],
"type": "object"
}
}
},
"description": "Success"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Usage reconciliation reports with evidence gaps and exception links",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "usage.reconciliation.run",
"x-rate-limit": "usage.reconciliation.read",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/usage/reconciliations
POST /api/v1/admin/usage/reconciliations
Enqueue usage reconciliation on the heavy queue
{
"parameters": [
{
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {},
"type": "object"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"properties": {
"job_id": {
"type": [
"string",
"null"
]
},
"queued": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"job_id",
"queued"
],
"type": "object"
}
}
},
"description": "Success"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Enqueue usage reconciliation on the heavy queue",
"tags": [
"usage"
],
"x-audit": "usage.reconciliation.run",
"x-body": "json",
"x-body-limit": 1024,
"x-idempotency": "required",
"x-permission": "usage.reconciliation.run",
"x-rate-limit": "usage.reconciliation.run",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/usage/servers/{id}
GET /api/v1/admin/usage/servers/{id}
Daily traffic drill-down
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "date_from",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "date_to",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageDaily"
}
}
},
"description": "Success"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Daily traffic drill-down",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "usage.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/usage/subscriptions/{id}
GET /api/v1/admin/usage/subscriptions/{id}
Daily traffic drill-down
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "date_from",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "date_to",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageDaily"
}
}
},
"description": "Success"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Daily traffic drill-down",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "usage.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/me/subscriptions/{id}/devices
GET /api/v1/me/subscriptions/{id}/devices
Online devices (masked addresses)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageDevices"
}
}
},
"description": "Success"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Online devices (masked addresses)",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/me/subscriptions/{id}/devices/{deviceKey}/kick
POST /api/v1/me/subscriptions/{id}/devices/{deviceKey}/kick
Block a device for 30 minutes
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "deviceKey",
"required": true,
"schema": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageKickedDevice"
}
}
},
"description": "Success"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"503": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "Block a device for 30 minutes",
"tags": [
"usage"
],
"x-audit": "usage.device.kick",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/me/subscriptions/{id}/usage
GET /api/v1/me/subscriptions/{id}/usage
My subscription daily traffic
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "date_from",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "date_to",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsageDaily"
}
}
},
"description": "Success"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Problem details"
}
},
"summary": "My subscription daily traffic",
"tags": [
"usage"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-reauth": false,
"effectiveSecurity": []
}