PPanel Edgesettings
由 openapi.json 自动生成的 10 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/settings
GET /api/v1/admin/settings
Settings domains the caller may read
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsDomainList"
}
}
},
"description": "Domains"
}
},
"summary": "Settings domains the caller may read",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "system.settings.read",
"effectiveSecurity": []
}GET /api/v1/admin/settings/{domain}
GET /api/v1/admin/settings/{domain}
Read one settings domain
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsDocument"
}
}
},
"description": "Document, with ETag",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "auth.forbidden"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Unknown or not served here"
}
},
"summary": "Read one settings domain",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "system.settings.read",
"effectiveSecurity": []
}PUT /api/v1/admin/settings/{domain}
PUT /api/v1/admin/settings/{domain}
Replace one settings domain (If-Match; write permission per domain; re-auth for secret-bearing domains)
Write permission per domain. Domains holding secrets (i18n, auth, captcha, storage, notify, webhooks) require a re-authentication within 10 minutes.
{
"description": "Write permission per domain. Domains holding secrets (i18n, auth, captcha, storage, notify, webhooks) require a re-authentication within 10 minutes.",
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"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/SettingsUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsDocument"
}
}
},
"description": "Saved document, with ETag",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "auth.forbidden or auth.reauth_required"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Unknown or not served here"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "common.version_conflict (with current) or an Idempotency-Key conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "If-Match missing"
}
},
"summary": "Replace one settings domain (If-Match; write permission per domain; re-auth for secret-bearing domains)",
"tags": [
"settings"
],
"x-audit": "system.settings.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "system.settings.read",
"effectiveSecurity": []
}GET /api/v1/admin/settings/{domain}/draft
GET /api/v1/admin/settings/{domain}/draft
Read the settings draft (v0 when absent)
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"draft": {
"allOf": [
{
"$ref": "#/components/schemas/SettingsRevision"
},
{
"type": [
"object",
"null"
]
}
]
}
},
"required": [
"draft"
],
"type": "object"
}
}
},
"description": "Settings revision result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Read the settings draft (v0 when absent)",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-idempotency": "none",
"x-permission": "system.settings.read",
"x-rate-limit": "settings.revisions.read",
"x-reauth": false,
"effectiveSecurity": []
}PUT /api/v1/admin/settings/{domain}/draft
PUT /api/v1/admin/settings/{domain}/draft
Save or explicitly rebase a draft; If-Match refers to the draft version
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"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": {
"base_version": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
},
"note": {
"maxLength": 2000,
"type": [
"string",
"null"
]
},
"value": {
"additionalProperties": {},
"type": "object"
}
},
"required": [
"value",
"base_version"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsRevision"
}
}
},
"description": "Settings revision result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Save or explicitly rebase a draft; If-Match refers to the draft version",
"tags": [
"settings"
],
"x-audit": "system.settings.draft",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "system.settings.read",
"x-rate-limit": "settings.revisions.write",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/settings/{domain}/publish
POST /api/v1/admin/settings/{domain}/publish
Publish the exact draft version; If-Match refers to the live settings version
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"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": {
"draft_version": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer"
},
"revision": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer"
}
},
"required": [
"revision",
"draft_version"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsDocument"
}
}
},
"description": "Settings revision result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Publish the exact draft version; If-Match refers to the live settings version",
"tags": [
"settings"
],
"x-audit": "system.settings.publish",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "system.settings.publish",
"x-rate-limit": "settings.revisions.write",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/settings/{domain}/revisions
GET /api/v1/admin/settings/{domain}/revisions
List settings revision metadata
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"exclusiveMinimum": 0,
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"base_version": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
},
"created_at": {
"type": "string"
},
"domain": {
"type": "string"
},
"note": {
"type": [
"string",
"null"
]
},
"published_at": {
"type": [
"string",
"null"
]
},
"revision": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"draft",
"published",
"superseded",
"rolled_back"
],
"type": "string"
},
"version": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
}
},
"required": [
"domain",
"revision",
"version",
"base_version",
"status",
"note",
"created_at",
"published_at"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"maximum": 2147483647,
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"type": "object"
}
}
},
"description": "Settings revision result"
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "List settings revision metadata",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "system.settings.publish",
"x-rate-limit": "settings.revisions.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/settings/{domain}/revisions/{revision}
GET /api/v1/admin/settings/{domain}/revisions/{revision}
Read a redacted settings revision
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
}
},
{
"in": "path",
"name": "revision",
"required": true,
"schema": {
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsRevision"
}
}
},
"description": "Settings revision result"
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Read a redacted settings revision",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "system.settings.publish",
"x-rate-limit": "settings.revisions.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/settings/{domain}/revisions/{revision}/diff
GET /api/v1/admin/settings/{domain}/revisions/{revision}/diff
Compare a revision with the current published settings; secret values are never returned
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
}
},
{
"in": "path",
"name": "revision",
"required": true,
"schema": {
"exclusiveMinimum": 0,
"maximum": 2147483647,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsRevisionDiff"
}
}
},
"description": "Settings revision result"
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Compare a revision with the current published settings; secret values are never returned",
"tags": [
"settings"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "system.settings.publish",
"x-rate-limit": "settings.revisions.read",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/settings/{domain}/rollback
POST /api/v1/admin/settings/{domain}/rollback
Restore a previously published revision as a new live version
{
"parameters": [
{
"in": "path",
"name": "domain",
"required": true,
"schema": {
"example": "site",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*$",
"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": {
"revision": {
"maximum": 2147483647,
"minimum": 1,
"type": "integer"
}
},
"required": [
"revision"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsDocument"
}
}
},
"description": "Settings revision result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"404": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"409": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"412": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"422": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
},
"428": {
"content": {
"application/problem+json": {
"schema": {}
}
},
"description": "Permission, revision, validation or concurrency error"
}
},
"summary": "Restore a previously published revision as a new live version",
"tags": [
"settings"
],
"x-audit": "system.settings.rollback",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "system.settings.publish",
"x-rate-limit": "settings.revisions.write",
"x-reauth": true,
"effectiveSecurity": []
}