PPanel Edgeops
由 openapi.json 自动生成的 26 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/alerts
GET /api/v1/admin/alerts
List exception alert routes
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/OpsAlertRoute"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
}
},
"description": "Alert routes"
}
},
"summary": "List exception alert routes",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.exception.read",
"effectiveSecurity": []
}POST /api/v1/admin/alerts
POST /api/v1/admin/alerts
Create an exception alert route
{
"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": {
"additionalProperties": false,
"properties": {
"channels": {
"items": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"maxItems": 4,
"minItems": 1,
"type": "array"
},
"enabled": {
"type": "boolean"
},
"exception_types": {
"items": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"severities": {
"items": {
"enum": [
"p1",
"p2",
"p3"
],
"type": "string"
},
"maxItems": 3,
"minItems": 1,
"type": "array"
},
"staff_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
},
"throttle_seconds": {
"maximum": 86400,
"minimum": 60,
"type": "integer"
}
},
"required": [
"name",
"enabled",
"exception_types",
"severities",
"staff_ids",
"channels",
"throttle_seconds"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpsAlertRoute"
}
}
},
"description": "Created route"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Recipients must be active staff"
}
},
"summary": "Create an exception alert route",
"tags": [
"ops"
],
"x-audit": "ops.alert.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "ops.exception.manage",
"x-rate-limit": "ops.manage.user",
"effectiveSecurity": []
}PUT /api/v1/admin/alerts/{id}
PUT /api/v1/admin/alerts/{id}
Update an exception alert route
{
"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"
}
},
{
"in": "header",
"name": "if-match",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channels": {
"items": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"maxItems": 4,
"minItems": 1,
"type": "array"
},
"enabled": {
"type": "boolean"
},
"exception_types": {
"items": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"name": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"severities": {
"items": {
"enum": [
"p1",
"p2",
"p3"
],
"type": "string"
},
"maxItems": 3,
"minItems": 1,
"type": "array"
},
"staff_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
},
"throttle_seconds": {
"maximum": 86400,
"minimum": 60,
"type": "integer"
}
},
"required": [
"name",
"enabled",
"exception_types",
"severities",
"staff_ids",
"channels",
"throttle_seconds"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpsAlertRoute"
}
}
},
"description": "Updated route",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown route"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Stale version"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Recipients must be active staff"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "Update an exception alert route",
"tags": [
"ops"
],
"x-audit": "ops.alert.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "ops.exception.manage",
"x-rate-limit": "ops.manage.user",
"effectiveSecurity": []
}GET /api/v1/admin/audit-events
GET /api/v1/admin/audit-events
Query audit events (newest first)
{
"parameters": [
{
"description": "Category; repeat the parameter for several values",
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"admin",
"security",
"billing",
"subscription",
"network",
"system",
"ops"
],
"type": "string"
},
{
"items": {
"enum": [
"admin",
"security",
"billing",
"subscription",
"network",
"system",
"ops"
],
"type": "string"
},
"type": "array"
}
],
"description": "Category; repeat the parameter for several values"
}
},
{
"description": "Outcome; repeat the parameter for several values",
"in": "query",
"name": "outcome",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"success",
"denied",
"failed"
],
"type": "string"
},
{
"items": {
"enum": [
"success",
"denied",
"failed"
],
"type": "string"
},
"type": "array"
}
],
"description": "Outcome; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "actor_type",
"required": false,
"schema": {
"enum": [
"user",
"staff",
"system",
"api_key",
"server"
],
"type": "string"
}
},
{
"in": "query",
"name": "actor_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "action",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "resource_type",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"description": "Use with resource_type",
"in": "query",
"name": "resource_id",
"required": false,
"schema": {
"description": "Use with resource_type",
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "request_id",
"required": false,
"schema": {
"maxLength": 128,
"minLength": 1,
"type": "string"
}
},
{
"description": "Occurred at or after (inclusive)",
"in": "query",
"name": "occurred_from",
"required": false,
"schema": {
"description": "Occurred at or after (inclusive)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Occurred before (exclusive)",
"in": "query",
"name": "occurred_to",
"required": false,
"schema": {
"description": "Occurred before (exclusive)",
"format": "date-time",
"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/AuditEventPage"
}
}
},
"description": "A page of audit events"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "Query audit events (newest first)",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.audit.read",
"effectiveSecurity": []
}GET /api/v1/admin/audit-events/{id}
GET /api/v1/admin/audit-events/{id}
One audit event
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"example": "42",
"pattern": "^[1-9]\\d{0,15}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditEvent"
}
}
},
"description": "The audit event"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such audit event"
}
},
"summary": "One audit event",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.audit.read",
"effectiveSecurity": []
}GET /api/v1/admin/exceptions
GET /api/v1/admin/exceptions
List business exceptions (newest first)
{
"parameters": [
{
"description": "Status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"open",
"acknowledged",
"muted",
"resolved"
],
"type": "string"
},
{
"items": {
"enum": [
"open",
"acknowledged",
"muted",
"resolved"
],
"type": "string"
},
"type": "array"
}
],
"description": "Status; repeat the parameter for several values"
}
},
{
"description": "Severity; repeat the parameter for several values",
"in": "query",
"name": "severity",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"p1",
"p2",
"p3"
],
"type": "string"
},
{
"items": {
"enum": [
"p1",
"p2",
"p3"
],
"type": "string"
},
"type": "array"
}
],
"description": "Severity; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "fingerprint",
"required": false,
"schema": {
"maxLength": 500,
"minLength": 1,
"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/OpsExceptionPage"
}
}
},
"description": "A page of exceptions"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List business exceptions (newest first)",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.exception.read",
"effectiveSecurity": []
}GET /api/v1/admin/exceptions/{id}
GET /api/v1/admin/exceptions/{id}
One business exception
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpsException"
}
}
},
"description": "The exception (ETag: its version)",
"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 exception"
}
},
"summary": "One business exception",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "ops.exception.read",
"effectiveSecurity": []
}POST /api/v1/admin/exceptions/{id}/handle
POST /api/v1/admin/exceptions/{id}/handle
Claim, assign, acknowledge, mute, resolve or comment on an exception
{
"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"
}
},
{
"in": "header",
"name": "if-match",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"action": {
"enum": [
"claim",
"assign",
"acknowledge",
"mute",
"unmute",
"resolve",
"comment"
],
"type": "string"
},
"note": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"owner_staff_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"action",
"note"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpsException"
}
}
},
"description": "Updated exception and handling history",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown exception"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Stale version or resolved exception"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid owner or note"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "Claim, assign, acknowledge, mute, resolve or comment on an exception",
"tags": [
"ops"
],
"x-audit": "ops.exception.handle",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "ops.exception.manage",
"x-rate-limit": "ops.manage.user",
"effectiveSecurity": []
}GET /api/v1/admin/exports
GET /api/v1/admin/exports
List own exports of a permitted kind
{
"parameters": [
{
"in": "query",
"name": "kind",
"required": true,
"schema": {
"enum": [
"orders",
"payments",
"users",
"usage",
"bulk_report"
],
"type": "string"
}
},
{
"in": "query",
"name": "operation_id",
"required": false,
"schema": {
"format": "uuid",
"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": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/OpsExport"
},
{
"$ref": "#/components/schemas/BulkReportExport"
}
]
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Own exports"
}
},
"summary": "List own exports of a permitted kind",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": [
"ops.export.orders",
"ops.export.payments",
"ops.export.users",
"ops.export.usage",
"ops.bulk.manage"
],
"effectiveSecurity": []
}POST /api/v1/admin/exports
POST /api/v1/admin/exports
Queue a private CSV export (at most 10,000 rows, expires after seven days)
{
"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": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": false,
"properties": {
"created_from": {
"format": "date-time",
"type": "string"
},
"created_to": {
"format": "date-time",
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"kind": {
"enum": [
"orders"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"row_limit": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"row_limit",
"reason",
"filters"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": false,
"properties": {
"created_from": {
"format": "date-time",
"type": "string"
},
"created_to": {
"format": "date-time",
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"kind": {
"enum": [
"payments"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"row_limit": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"row_limit",
"reason",
"filters"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": false,
"properties": {
"created_from": {
"format": "date-time",
"type": "string"
},
"created_to": {
"format": "date-time",
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"kind": {
"enum": [
"users"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"row_limit": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"row_limit",
"reason",
"filters"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": false,
"properties": {
"operation_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"operation_id"
],
"type": "object"
},
"kind": {
"enum": [
"bulk_report"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"row_limit": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"row_limit",
"reason",
"filters"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"filters": {
"additionalProperties": false,
"properties": {
"date_from": {
"format": "date",
"type": "string"
},
"date_to": {
"format": "date",
"type": "string"
},
"server_id": {
"format": "uuid",
"type": "string"
},
"subscription_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"date_from",
"date_to"
],
"type": "object"
},
"kind": {
"enum": [
"usage"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"row_limit": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"kind",
"row_limit",
"reason",
"filters"
],
"type": "object"
}
]
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/OpsExport"
},
{
"$ref": "#/components/schemas/BulkReportExport"
}
]
}
}
},
"description": "Queued export"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Export-kind permission required"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such bulk operation"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid export request"
},
"429": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Export quota exceeded"
}
},
"summary": "Queue a private CSV export (at most 10,000 rows, expires after seven days)",
"tags": [
"ops"
],
"x-audit": "ops.export.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": [
"ops.export.orders",
"ops.export.payments",
"ops.export.users",
"ops.export.usage",
"ops.bulk.manage"
],
"x-rate-limit": "ops.export.user",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/exports/{id}
GET /api/v1/admin/exports/{id}
Read own export status
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/OpsExport"
},
{
"$ref": "#/components/schemas/BulkReportExport"
}
]
}
}
},
"description": "Export status"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such export"
}
},
"summary": "Read own export status",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": [
"ops.export.orders",
"ops.export.payments",
"ops.export.users",
"ops.export.usage",
"ops.bulk.manage"
],
"effectiveSecurity": []
}GET /api/v1/admin/exports/{id}/download
GET /api/v1/admin/exports/{id}/download
Download an unexpired private export
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"text/csv": {
"schema": {
"type": "string"
}
}
},
"description": "Private CSV download"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Export missing, pending, expired, or owned by another operator"
}
},
"summary": "Download an unexpired private export",
"tags": [
"ops"
],
"x-audit": "ops.export.download",
"x-body": "none",
"x-body-limit": 0,
"x-permission": [
"ops.export.orders",
"ops.export.payments",
"ops.export.users",
"ops.export.usage",
"ops.bulk.manage"
],
"effectiveSecurity": []
}GET /api/v1/admin/jobs
GET /api/v1/admin/jobs
List jobs (newest first)
{
"parameters": [
{
"description": "Job status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"pending",
"running",
"succeeded",
"dead",
"cancelled"
],
"type": "string"
},
{
"items": {
"enum": [
"pending",
"running",
"succeeded",
"dead",
"cancelled"
],
"type": "string"
},
"type": "array"
}
],
"description": "Job status; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "queue",
"required": false,
"schema": {
"enum": [
"default",
"heavy"
],
"type": "string"
}
},
{
"in": "query",
"name": "kind",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "dedupe_key",
"required": false,
"schema": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"description": "Created at or after (inclusive)",
"in": "query",
"name": "created_from",
"required": false,
"schema": {
"description": "Created at or after (inclusive)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Created before (exclusive)",
"in": "query",
"name": "created_to",
"required": false,
"schema": {
"description": "Created before (exclusive)",
"format": "date-time",
"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/JobPage"
}
}
},
"description": "A page of jobs"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List jobs (newest first)",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.job.read",
"effectiveSecurity": []
}GET /api/v1/admin/jobs/stats
GET /api/v1/admin/jobs/stats
Job statistics per queue and kind
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobStats"
}
}
},
"description": "Current gauges and failure/supersede occurrences within the last hour"
}
},
"summary": "Job statistics per queue and kind",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "ops.job.read",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/jobs/{id}
GET /api/v1/admin/jobs/{id}
Job detail with the redacted payload
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"example": "42",
"pattern": "^[1-9]\\d{0,15}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobDetail"
}
}
},
"description": "The job"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such job"
}
},
"summary": "Job detail with the redacted payload",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.job.read",
"effectiveSecurity": []
}POST /api/v1/admin/jobs/{id}/cancel
POST /api/v1/admin/jobs/{id}/cancel
Cancel a pending or dead job
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"example": "42",
"pattern": "^[1-9]\\d{0,15}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobDetail"
}
}
},
"description": "The cancelled job"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such job"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "system.job_not_cancellable: the job is running or finished"
}
},
"summary": "Cancel a pending or dead job",
"tags": [
"ops"
],
"x-audit": "ops.job.cancel",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "ops.job.manage",
"effectiveSecurity": []
}POST /api/v1/admin/jobs/{id}/replay
POST /api/v1/admin/jobs/{id}/replay
Replay a dead job (dead → pending, attempts reset)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"example": "42",
"pattern": "^[1-9]\\d{0,15}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobReplayResult"
}
}
},
"description": "Requeued, or cancelled as superseded"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such job"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "system.job_not_replayable: the job is not dead"
}
},
"summary": "Replay a dead job (dead → pending, attempts reset)",
"tags": [
"ops"
],
"x-audit": "ops.job.replay",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "ops.job.manage",
"effectiveSecurity": []
}GET /api/v1/admin/keys/inventory
GET /api/v1/admin/keys/inventory
Inventory every master-key envelope and live hardware HMAC dependency
{
"parameters": [
{
"in": "query",
"name": "old_version",
"required": false,
"schema": {
"exclusiveMinimum": 0,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MasterKeyInventory"
}
}
},
"description": "Coherent database snapshot; excludes offline backups"
}
},
"summary": "Inventory every master-key envelope and live hardware HMAC dependency",
"tags": [
"ops"
],
"x-audit": "ops.keys.inventory",
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.job.read",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/keys/reencrypt
POST /api/v1/admin/keys/reencrypt
Start bounded resumable global re-encryption; progress is available in the job console
{
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"properties": {
"job_id": {
"type": "string"
}
},
"required": [
"job_id"
],
"type": "object"
}
}
},
"description": "First rotation batch enqueued"
}
},
"summary": "Start bounded resumable global re-encryption; progress is available in the job console",
"tags": [
"ops"
],
"x-audit": "ops.keys.reencrypt",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"x-permission": "ops.job.manage",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/logs
GET /api/v1/admin/logs
Search bounded local runtime logs or open Workers Logs
{
"parameters": [
{
"in": "query",
"name": "level",
"required": false,
"schema": {
"enum": [
"debug",
"info",
"warn",
"error"
],
"type": "string"
}
},
{
"in": "query",
"name": "from_at",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "to_at",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "keyword",
"required": false,
"schema": {
"maxLength": 256,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "request_id",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
"type": "string"
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9._:-]{1,128}$",
"type": "string"
}
},
{
"in": "query",
"name": "instance_id",
"required": false,
"schema": {
"pattern": "^[A-Za-z0-9._:-]{1,128}$",
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"dashboard_prefill_verified": {
"enum": [
false
],
"type": "boolean"
},
"dashboard_url": {
"type": [
"string",
"null"
]
},
"filter_context": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"additionalProperties": {},
"properties": {
"instance_id": {
"type": "string"
},
"level": {
"enum": [
"debug",
"info",
"warn",
"error"
],
"type": "string"
},
"msg": {
"type": "string"
},
"request_id": {
"type": "string"
},
"source": {
"type": "string"
},
"time": {
"type": "string"
}
},
"required": [
"time",
"level",
"msg",
"source",
"instance_id"
],
"type": "object"
},
"type": "array"
},
"mode": {
"enum": [
"selfhost",
"workers",
"disabled"
],
"type": "string"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": "string"
},
"scan_limit_reached": {
"type": "boolean"
},
"scanned_bytes": {
"type": "integer"
}
},
"required": [
"request_id",
"mode",
"items",
"next_cursor",
"has_more",
"scanned_bytes",
"scan_limit_reached",
"dashboard_url",
"dashboard_prefill_verified",
"filter_context"
],
"type": "object"
}
}
},
"description": "Runtime logs, newest write first"
}
},
"summary": "Search bounded local runtime logs or open Workers Logs",
"tags": [
"ops"
],
"x-audit": "ops.logs.read",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "ops.logs.read",
"x-rate-limit": "ops.logs.read",
"x-reauth": false,
"effectiveSecurity": []
}PUT /api/v1/admin/maintenance
PUT /api/v1/admin/maintenance
Freeze or resume writes and background work
{
"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": {
"enabled": {
"type": "boolean"
},
"reason": {
"maxLength": 500,
"minLength": 10,
"type": "string"
},
"retry_after_seconds": {
"maximum": 86400,
"minimum": 1,
"type": "integer"
}
},
"required": [
"enabled",
"retry_after_seconds",
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaintenanceState"
}
}
},
"description": "Updated switch",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Concurrent change"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "Freeze or resume writes and background work",
"tags": [
"ops"
],
"x-audit": "platform.maintenance.set",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "system.maintenance.manage",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/repairs
GET /api/v1/admin/repairs
List repair commands (newest first)
{
"parameters": [
{
"description": "Status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"previewed",
"executing",
"succeeded",
"partial",
"failed",
"expired"
],
"type": "string"
},
{
"items": {
"enum": [
"previewed",
"executing",
"succeeded",
"partial",
"failed",
"expired"
],
"type": "string"
},
"type": "array"
}
],
"description": "Status; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "command",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "target_type",
"required": false,
"schema": {
"maxLength": 100,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "target_id",
"required": false,
"schema": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "operator_id",
"required": false,
"schema": {
"format": "uuid",
"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/RepairCommandPage"
}
}
},
"description": "A page of repair commands"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "List repair commands (newest first)",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.repair.read",
"effectiveSecurity": []
}GET /api/v1/admin/repairs/catalog
GET /api/v1/admin/repairs/catalog
Repair command catalogue
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairCatalogue"
}
}
},
"description": "Registered repair commands"
}
},
"summary": "Repair command catalogue",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.repair.read",
"effectiveSecurity": []
}POST /api/v1/admin/repairs/preview
POST /api/v1/admin/repairs/preview
Preview a repair command (valid for 10 minutes)
{
"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": {
"properties": {
"command": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"input": {
"additionalProperties": {},
"description": "Command input, see the catalogue",
"type": "object"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"command",
"input",
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairCommand"
}
}
},
"description": "The previewed command (the same record again for a repeated key)"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden: the command permission is missing"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.idempotency_key_reused, or a business conflict raised by the command preview"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown command or invalid input"
}
},
"summary": "Preview a repair command (valid for 10 minutes)",
"tags": [
"ops"
],
"x-audit": "ops.repair.preview",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "ops.repair.read",
"effectiveSecurity": []
}GET /api/v1/admin/repairs/{id}
GET /api/v1/admin/repairs/{id}
One repair command
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairCommand"
}
}
},
"description": "The repair command"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such repair command"
}
},
"summary": "One repair command",
"tags": [
"ops"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ops.repair.read",
"effectiveSecurity": []
}POST /api/v1/admin/repairs/{id}/execute
POST /api/v1/admin/repairs/{id}/execute
Execute a previewed repair command
{
"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": {
"properties": {
"expected_version": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
"required": [
"expected_version"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepairCommand"
}
}
},
"description": "The executed command; a finished command returns its first result"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.forbidden: the command permission is missing"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such repair command"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "ops.repair_preview_expired, ops.repair_target_changed, common.version_conflict (expected_version is not the preview's), or a business conflict raised by the command"
}
},
"summary": "Execute a previewed repair command",
"tags": [
"ops"
],
"x-audit": "ops.repair.execute",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "ops.repair.read",
"x-reauth": true,
"effectiveSecurity": []
}