PPanel Edgenetwork
由 openapi.json 自动生成的 40 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
DELETE /api/v1/admin/network/inbounds/{id}
DELETE /api/v1/admin/network/inbounds/{id}
Delete an inbound that has no nodes (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.inbound_in_use (details.node_count) or common.version_conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Delete an inbound that has no nodes (If-Match)",
"tags": [
"network"
],
"x-audit": "network.inbound.delete",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.inbound.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/inbounds/{id}
GET /api/v1/admin/network/inbounds/{id}
One inbound (secrets as { "set": true }), with ETag
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInbound"
}
}
},
"description": "The inbound",
"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 inbound"
}
},
"summary": "One inbound (secrets as { \"set\": true }), with ETag",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "network.server.read",
"effectiveSecurity": []
}PUT /api/v1/admin/network/inbounds/{id}
PUT /api/v1/admin/network/inbounds/{id}
Replace an inbound (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInboundInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInbound"
}
}
},
"description": "The inbound, with ETag"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server or inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.port_conflict, network.server_retired or common.version_conflict"
},
"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": "network.protocol_params_invalid or common.validation_failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace an inbound (If-Match)",
"tags": [
"network"
],
"x-audit": "network.inbound.update",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "network.inbound.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/inbounds/{id}/secret
GET /api/v1/admin/network/inbounds/{id}/secret
Plaintext secrets of an inbound (re-authentication within 10 minutes; audited)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInboundSecrets"
}
}
},
"description": "Secrets by parameter path"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such inbound"
}
},
"summary": "Plaintext secrets of an inbound (re-authentication within 10 minutes; audited)",
"tags": [
"network"
],
"x-audit": "network.inbound.read_secret",
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.inbound.read_secret",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/network/inbounds/{id}/status
POST /api/v1/admin/network/inbounds/{id}/status
Enable or disable an inbound (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"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": {
"$ref": "#/components/schemas/NetworkInboundStatusInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInbound"
}
}
},
"description": "The inbound, with ETag",
"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 server or inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.port_conflict, network.server_retired or common.version_conflict"
},
"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": "network.protocol_params_invalid or common.validation_failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Enable or disable an inbound (If-Match)",
"tags": [
"network"
],
"x-audit": "network.inbound.status",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.inbound.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/multipliers
GET /api/v1/admin/network/multipliers
Versioned time-of-day traffic rules
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"rules": {
"additionalProperties": false,
"properties": {
"global": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"inbounds": {
"additionalProperties": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"type": "object"
}
},
"required": [
"global",
"inbounds"
],
"type": "object"
},
"version": {
"type": "integer"
}
},
"required": [
"rules",
"version"
],
"type": "object"
}
}
},
"description": "Rules; weekdays start on Sunday",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Versioned time-of-day traffic rules",
"tags": [
"network"
],
"x-audit": "network.multiplier.read",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-idempotency": "none",
"x-permission": "network.server.read",
"x-rate-limit": "network.multiplier.read",
"x-reauth": false,
"effectiveSecurity": []
}PUT /api/v1/admin/network/multipliers
PUT /api/v1/admin/network/multipliers
Replace time-of-day traffic rules
{
"parameters": [
{
"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": {
"rules": {
"additionalProperties": false,
"properties": {
"global": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"inbounds": {
"additionalProperties": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"type": "object"
}
},
"required": [
"global",
"inbounds"
],
"type": "object"
}
},
"required": [
"rules"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"rules": {
"additionalProperties": false,
"properties": {
"global": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"inbounds": {
"additionalProperties": {
"items": {
"additionalProperties": false,
"properties": {
"days": {
"items": {
"maximum": 6,
"minimum": 0,
"type": "integer"
},
"maxItems": 7,
"minItems": 1,
"type": "array"
},
"end": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
},
"id": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"multiplier_bps": {
"maximum": 1000000,
"minimum": 1,
"type": "integer"
},
"priority": {
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"start": {
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority"
],
"type": "object"
},
"maxItems": 100,
"type": "array"
},
"type": "object"
}
},
"required": [
"global",
"inbounds"
],
"type": "object"
},
"version": {
"type": "integer"
}
},
"required": [
"rules",
"version"
],
"type": "object"
}
}
},
"description": "Saved rules",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Inbound not found"
},
"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 rules"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace time-of-day traffic rules",
"tags": [
"network"
],
"x-audit": "network.multiplier.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.runtime.manage",
"x-rate-limit": "network.multiplier.write",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/network/multipliers/preview
GET /api/v1/admin/network/multipliers/preview
Effective multiplier now or at an explicit instant
{
"parameters": [
{
"in": "query",
"name": "inbound_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "at",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"at": {
"format": "date-time",
"type": "string"
},
"base_multiplier": {
"type": "string"
},
"effective_multiplier": {
"type": "string"
},
"inbound_id": {
"format": "uuid",
"type": "string"
},
"multiplier_bps": {
"type": "integer"
},
"rule_id": {
"type": [
"string",
"null"
]
},
"rule_version": {
"type": "integer"
},
"scope": {
"enum": [
"inbound",
"global",
"default"
],
"type": "string"
},
"timezone": {
"type": "string"
},
"windows": {
"items": {
"properties": {
"days": {
"items": {
"type": "integer"
},
"type": "array"
},
"effective_multiplier": {
"type": "string"
},
"end": {
"type": "string"
},
"id": {
"type": "string"
},
"multiplier_bps": {
"type": "integer"
},
"priority": {
"type": "integer"
},
"scope": {
"enum": [
"inbound",
"global"
],
"type": "string"
},
"start": {
"type": "string"
}
},
"required": [
"id",
"days",
"start",
"end",
"multiplier_bps",
"priority",
"scope",
"effective_multiplier"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"inbound_id",
"at",
"timezone",
"rule_version",
"base_multiplier",
"multiplier_bps",
"rule_id",
"scope",
"effective_multiplier",
"windows"
],
"type": "object"
}
}
},
"description": "Effective multiplier and windows"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Inbound not found"
}
},
"summary": "Effective multiplier now or at an explicit instant",
"tags": [
"network"
],
"x-audit": "network.multiplier.read",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "network.server.read",
"x-rate-limit": "network.multiplier.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/network/nodes
GET /api/v1/admin/network/nodes
List nodes (sort, id order)
{
"parameters": [
{
"description": "Name or connect host contains",
"in": "query",
"name": "q",
"required": false,
"schema": {
"description": "Name or connect host contains",
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "server_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "inbound_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Manual tag the node carries",
"in": "query",
"name": "tag",
"required": false,
"schema": {
"description": "Manual tag the node carries",
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
{
"description": "Visibility; repeat the parameter for several values",
"in": "query",
"name": "visibility",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"visible",
"hidden",
"disabled"
],
"type": "string"
},
{
"items": {
"enum": [
"visible",
"hidden",
"disabled"
],
"type": "string"
},
"type": "array"
}
],
"description": "Visibility; repeat the parameter for several values"
}
},
{
"description": "Kind; repeat the parameter for several values",
"in": "query",
"name": "kind",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"direct",
"relay",
"cdn"
],
"type": "string"
},
{
"items": {
"enum": [
"direct",
"relay",
"cdn"
],
"type": "string"
},
"type": "array"
}
],
"description": "Kind; repeat the parameter for several values"
}
},
{
"description": "Address family; repeat the parameter for several values",
"in": "query",
"name": "address_family",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"ipv4",
"ipv6",
"dual"
],
"type": "string"
},
{
"items": {
"enum": [
"ipv4",
"ipv6",
"dual"
],
"type": "string"
},
"type": "array"
}
],
"description": "Address family; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "region_code",
"required": false,
"schema": {
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodePage"
}
}
},
"description": "A page of nodes"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List nodes (sort, id order)",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}POST /api/v1/admin/network/nodes
POST /api/v1/admin/network/nodes
Create a node
{
"parameters": [
{
"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"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeInput"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNode"
}
}
},
"description": "The node, with ETag"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such node or inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired or common.version_conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.tag_invalid or common.validation_failed"
}
},
"summary": "Create a node",
"tags": [
"network"
],
"x-audit": "network.node.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/nodes/reorder
POST /api/v1/admin/network/nodes/reorder
Set the order of nodes
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeReorderInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeReorderResult"
}
}
},
"description": "Updated count"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
}
},
"summary": "Set the order of nodes",
"tags": [
"network"
],
"x-audit": "network.node.reorder",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/nodes/tags
POST /api/v1/admin/network/nodes/tags
Add or remove manual tags on many nodes
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeTagsInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeTagsResult"
}
}
},
"description": "Nodes whose tags changed"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.tag_invalid or common.validation_failed"
}
},
"summary": "Add or remove manual tags on many nodes",
"tags": [
"network"
],
"x-audit": "network.node.tags",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}DELETE /api/v1/admin/network/nodes/{id}
DELETE /api/v1/admin/network/nodes/{id}
Delete a node (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such node"
},
"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"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Delete a node (If-Match)",
"tags": [
"network"
],
"x-audit": "network.node.delete",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/nodes/{id}
GET /api/v1/admin/network/nodes/{id}
One node, with ETag
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNode"
}
}
},
"description": "The node",
"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 node"
}
},
"summary": "One node, with ETag",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "network.server.read",
"effectiveSecurity": []
}PUT /api/v1/admin/network/nodes/{id}
PUT /api/v1/admin/network/nodes/{id}
Replace a node (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNode"
}
}
},
"description": "The node, with ETag"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such node or inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired or common.version_conflict"
},
"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": "network.tag_invalid or common.validation_failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace a node (If-Match)",
"tags": [
"network"
],
"x-audit": "network.node.update",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/protocols
GET /api/v1/admin/network/protocols
Protocol catalogue for the inbound forms
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkProtocolList"
}
}
},
"description": "Protocols"
}
},
"summary": "Protocol catalogue for the inbound forms",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}GET /api/v1/admin/network/runtime
GET /api/v1/admin/network/runtime
Runtime defaults of every server, with ETag
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkRuntimeDefaults"
}
}
},
"description": "Runtime defaults",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "Runtime defaults of every server, with ETag",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "network.server.read",
"effectiveSecurity": []
}PUT /api/v1/admin/network/runtime
PUT /api/v1/admin/network/runtime
Replace the runtime defaults (If-Match); servers re-render their desired config
{
"parameters": [
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkRuntimeDefaultsInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkRuntimeDefaults"
}
}
},
"description": "Saved defaults, with ETag",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"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": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace the runtime defaults (If-Match); servers re-render their desired config",
"tags": [
"network"
],
"x-audit": "network.runtime.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.runtime.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers
GET /api/v1/admin/network/servers
List servers (sort, id order)
{
"parameters": [
{
"description": "Name or address contains",
"in": "query",
"name": "q",
"required": false,
"schema": {
"description": "Name or address contains",
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
{
"description": "Status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"active",
"maintenance",
"retired"
],
"type": "string"
},
{
"items": {
"enum": [
"active",
"maintenance",
"retired"
],
"type": "string"
},
"type": "array"
}
],
"description": "Status; repeat the parameter for several values"
}
},
{
"description": "Health; repeat the parameter for several values",
"in": "query",
"name": "health",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"unknown",
"healthy",
"degraded",
"offline",
"config_drift",
"auth_failed",
"protocol_conflict"
],
"type": "string"
},
{
"items": {
"enum": [
"unknown",
"healthy",
"degraded",
"offline",
"config_drift",
"auth_failed",
"protocol_conflict"
],
"type": "string"
},
"type": "array"
}
],
"description": "Health; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "region_code",
"required": false,
"schema": {
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"type": "string"
}
},
{
"in": "query",
"name": "ip_geo_status",
"required": false,
"schema": {
"enum": [
"ok",
"unresolved",
"manual"
],
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerPage"
}
}
},
"description": "A page of servers"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List servers (sort, id order)",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers
POST /api/v1/admin/network/servers
Create a server (renders desired config revision 1)
{
"parameters": [
{
"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"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerInput"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "The server, with ETag",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
}
},
"summary": "Create a server (renders desired config revision 1)",
"tags": [
"network"
],
"x-audit": "network.server.create",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true
},
"x-idempotency": "required",
"x-permission": "network.server.manage",
"effectiveSecurity": []
}DELETE /api/v1/admin/network/servers/{id}
DELETE /api/v1/admin/network/servers/{id}
Retire a server (If-Match): terminal; its nodes stop authorizing anyone
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "The retired server",
"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 server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict or network.server_retired"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Retire a server (If-Match): terminal; its nodes stop authorizing anyone",
"tags": [
"network"
],
"x-audit": "network.server.retire",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.server.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers/{id}
GET /api/v1/admin/network/servers/{id}
One server, with ETag
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "The server",
"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 server"
}
},
"summary": "One server, with ETag",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "network.server.read",
"effectiveSecurity": []
}PUT /api/v1/admin/network/servers/{id}
PUT /api/v1/admin/network/servers/{id}
Edit a server (If-Match): name, location, address, active ⇄ maintenance, order
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"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": {
"$ref": "#/components/schemas/NetworkServerInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "The server, with ETag",
"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 server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict or network.server_retired"
},
"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": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Edit a server (If-Match): name, location, address, active ⇄ maintenance, order",
"tags": [
"network"
],
"x-audit": "network.server.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.server.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers/{id}/config
GET /api/v1/admin/network/servers/{id}/config
Runtime configuration and desired config preview (secrets masked)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerConfig"
}
}
},
"description": "Configuration",
"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 server"
}
},
"summary": "Runtime configuration and desired config preview (secrets masked)",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "network.server.read",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/create-ipv6-node
POST /api/v1/admin/network/servers/{id}/create-ipv6-node
Create IPv6 twins of the direct IPv4 nodes (needs a reported IPv6 address)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Only these IPv4 nodes; default every direct IPv4 node of the server",
"in": "query",
"name": "node_id",
"required": false,
"schema": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"type": "array"
}
],
"description": "Only these IPv4 nodes; default every direct IPv4 node of the server"
}
},
{
"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": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkNodeList"
}
}
},
"description": "Created nodes"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired, network.agent_not_active or network.ipv6_unavailable"
}
},
"summary": "Create IPv6 twins of the direct IPv4 nodes (needs a reported IPv6 address)",
"tags": [
"network"
],
"x-audit": "network.node.create_ipv6",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/disable-agent
POST /api/v1/admin/network/servers/{id}/disable-agent
Disable the agent (node gets 403 node.disabled until it enrolls again)
{
"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"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "The server"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired, network.agent_not_active or network.ipv6_unavailable"
}
},
"summary": "Disable the agent (node gets 403 node.disabled until it enrolls again)",
"tags": [
"network"
],
"x-audit": "network.agent.disable",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "network.agent.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/enrollment-token
POST /api/v1/admin/network/servers/{id}/enrollment-token
Issue a one-time enrollment token (1 hour)
{
"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"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkAgentToken"
}
}
},
"description": "The token (shown once)"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired, network.agent_not_active or network.ipv6_unavailable"
}
},
"summary": "Issue a one-time enrollment token (1 hour)",
"tags": [
"network"
],
"x-audit": "network.agent.enrollment_token",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "network.agent.manage",
"effectiveSecurity": []
}PUT /api/v1/admin/network/servers/{id}/geo
PUT /api/v1/admin/network/servers/{id}/geo
Set a manual server location, protected from automatic GeoIP refresh
{
"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": {
"country_code": {
"pattern": "^[A-Z]{2}$",
"type": [
"string",
"null"
]
},
"region_code": {
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"type": [
"string",
"null"
]
}
},
"required": [
"country_code",
"region_code"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServer"
}
}
},
"description": "Server location",
"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 server"
},
"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 location"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Set a manual server location, protected from automatic GeoIP refresh",
"tags": [
"network"
],
"x-audit": "network.server.geo",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "network.server.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers/{id}/health
GET /api/v1/admin/network/servers/{id}/health
Server health: stored state and the live verdict with reasons
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerHealth"
}
}
},
"description": "Health"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
}
},
"summary": "Server health: stored state and the live verdict with reasons",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers/{id}/inbounds
GET /api/v1/admin/network/servers/{id}/inbounds
A server's inbounds
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInboundList"
}
}
},
"description": "Inbounds"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
}
},
"summary": "A server's inbounds",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/inbounds
POST /api/v1/admin/network/servers/{id}/inbounds
Create an inbound; the desired config is re-rendered in the same transaction
{
"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"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInboundInput"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkInbound"
}
}
},
"description": "The inbound, with ETag"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server or inbound"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.port_conflict, network.server_retired or common.version_conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.protocol_params_invalid or common.validation_failed"
}
},
"summary": "Create an inbound; the desired config is re-rendered in the same transaction",
"tags": [
"network"
],
"x-audit": "network.inbound.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "network.inbound.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/republish
POST /api/v1/admin/network/servers/{id}/republish
Re-render the desired config now
{
"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"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkRepublish"
}
}
},
"description": "Render result"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired, network.agent_not_active or network.ipv6_unavailable"
}
},
"summary": "Re-render the desired config now",
"tags": [
"network"
],
"x-audit": "network.agent.republish",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "network.agent.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/servers/{id}/rotate-agent-token
POST /api/v1/admin/network/servers/{id}/rotate-agent-token
Rotate the agent token (10-minute overlap unless immediate revocation is selected)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Revoke immediately (token leaked); default false keeps the 10-minute overlap",
"in": "query",
"name": "immediate",
"required": false,
"schema": {
"default": "false",
"description": "Revoke immediately (token leaked); default false keeps the 10-minute overlap",
"enum": [
"true",
"false"
],
"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": {
"$ref": "#/components/schemas/NetworkAgentToken"
}
}
},
"description": "The new token (shown once); expires_at is the previous token cut-off time"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden or auth.reauth_required"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.server_retired, network.agent_not_active or network.ipv6_unavailable"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid immediate option"
}
},
"summary": "Rotate the agent token (10-minute overlap unless immediate revocation is selected)",
"tags": [
"network"
],
"x-audit": "network.agent.rotate_token",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "network.agent.manage",
"x-reauth": true,
"effectiveSecurity": []
}PUT /api/v1/admin/network/servers/{id}/runtime
PUT /api/v1/admin/network/servers/{id}/runtime
Replace the runtime override patch (If-Match = server ETag); re-renders the desired config
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"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": {
"$ref": "#/components/schemas/NetworkRuntimeOverridesInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerConfig"
}
}
},
"description": "Configuration, with the server ETag",
"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 server"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict or network.server_retired"
},
"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": "Validation failed (e.g. a rule names an unknown outbound)"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace the runtime override patch (If-Match = server ETag); re-renders the desired config",
"tags": [
"network"
],
"x-audit": "network.server.runtime_update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "network.runtime.manage",
"effectiveSecurity": []
}GET /api/v1/admin/network/servers/{id}/stats
GET /api/v1/admin/network/servers/{id}/stats
Daily load and speed statistics (business dates)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Business date (inclusive); default 29 days before date_to",
"in": "query",
"name": "date_from",
"required": false,
"schema": {
"description": "Business date (inclusive); default 29 days before date_to",
"example": "2026-10-22",
"format": "date",
"type": "string"
}
},
{
"description": "Business date (inclusive); default today",
"in": "query",
"name": "date_to",
"required": false,
"schema": {
"description": "Business date (inclusive); default today",
"example": "2026-10-22",
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkServerStats"
}
}
},
"description": "Statistics"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such server"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid range"
}
},
"summary": "Daily load and speed statistics (business dates)",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}GET /api/v1/admin/network/tags
GET /api/v1/admin/network/tags
Tag summary: manual tags (nodes, plans, active subscriptions) and system tags
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagList"
}
}
},
"description": "Tags"
}
},
"summary": "Tag summary: manual tags (nodes, plans, active subscriptions) and system tags",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}GET /api/v1/admin/network/tags/impact
GET /api/v1/admin/network/tags/impact
What renaming or merging these tags would touch
{
"parameters": [
{
"description": "Tags to inspect; repeat the parameter for several",
"in": "query",
"name": "tags",
"required": true,
"schema": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"items": {
"maxLength": 128,
"type": "string"
},
"maxItems": 64,
"type": "array"
}
],
"description": "Tags to inspect; repeat the parameter for several"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagImpact"
}
}
},
"description": "Counts per tag"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
}
},
"summary": "What renaming or merging these tags would touch",
"tags": [
"network"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "network.server.read",
"effectiveSecurity": []
}POST /api/v1/admin/network/tags/merge
POST /api/v1/admin/network/tags/merge
Merge tags into one on nodes, plans and subscriptions in one transaction
{
"parameters": [
{
"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"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagMergeInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagChange"
}
}
},
"description": "What changed"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden: catalog.plan.manage is also required"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.tag_invalid (system tag shape, unknown source, existing target for a rename)"
}
},
"summary": "Merge tags into one on nodes, plans and subscriptions in one transaction",
"tags": [
"network"
],
"x-audit": "network.tag.merge",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}POST /api/v1/admin/network/tags/rename
POST /api/v1/admin/network/tags/rename
Rename a tag on nodes, plans and subscriptions in one transaction
{
"parameters": [
{
"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"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagRenameInput"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NetworkTagChange"
}
}
},
"description": "What changed"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden: catalog.plan.manage is also required"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "network.tag_invalid (system tag shape, unknown source, existing target for a rename)"
}
},
"summary": "Rename a tag on nodes, plans and subscriptions in one transaction",
"tags": [
"network"
],
"x-audit": "network.tag.rename",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "network.node.manage",
"effectiveSecurity": []
}GET /api/v1/me/subscriptions/{id}/node-multipliers
GET /api/v1/me/subscriptions/{id}/node-multipliers
Current effective multipliers for my subscription nodes
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"at": {
"format": "date-time",
"type": "string"
},
"nodes": {
"items": {
"properties": {
"effective_multiplier": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"rule_version": {
"type": "integer"
}
},
"required": [
"id",
"effective_multiplier",
"rule_version"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"at",
"nodes"
],
"type": "object"
}
}
},
"description": "Current rates"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Subscription not found"
}
},
"summary": "Current effective multipliers for my subscription nodes",
"tags": [
"network"
],
"x-audit": "network.multiplier.read",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-rate-limit": "network.multiplier.read",
"x-reauth": false,
"effectiveSecurity": []
}