PPanel Edge数据模型
openapi.json 中全部可复用的 schema、安全方案与组件定义。
自动生成的共享组件定义。
{
"parameters": {},
"schemas": {
"AdminMe": {
"properties": {
"capabilities": {
"items": {
"type": "string"
},
"type": "array"
},
"email": {
"type": "string"
},
"locale": {
"type": "string"
},
"mfa": {
"properties": {
"enrolled": {
"type": "boolean"
},
"required": {
"enum": [
"enrollment",
"verification",
null
],
"type": [
"string",
"null"
]
},
"verified_at": {
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"enrolled",
"verified_at",
"required"
],
"type": "object"
},
"name": {
"type": "string"
},
"permissions": {
"items": {
"type": "string"
},
"type": "array"
},
"permissions_etag": {
"type": [
"string",
"null"
]
},
"reauth_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"session_expires_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"email",
"name",
"locale",
"roles",
"permissions",
"capabilities",
"mfa",
"reauth_at",
"session_expires_at",
"permissions_etag"
],
"type": "object"
},
"AdminSubscription": {
"allOf": [
{
"$ref": "#/components/schemas/MySubscription"
},
{
"properties": {
"access_version": {
"type": "integer"
},
"auto_renew_failures": {
"type": "integer"
},
"available_actions": {
"items": {
"enum": [
"extend",
"grant_traffic",
"set_limits",
"suspend",
"resume",
"cancel",
"reset_usage",
"rotate_credential",
"activate",
"disable_auto_renew"
],
"type": "string"
},
"type": "array"
},
"credential": {
"properties": {
"fingerprint": {
"description": "Lowercase hex SHA-256 of the node UUID text",
"type": "string"
},
"rotated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"fingerprint",
"rotated_at"
],
"type": "object"
},
"device_bonus": {
"description": "Part of device_limit added by applied device bonuses",
"type": "integer"
},
"link": {
"properties": {
"fingerprint": {
"description": "Lowercase hex SHA-256 of the link token",
"type": [
"string",
"null"
]
},
"issued": {
"type": "boolean"
},
"last_fetched_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"rotated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"issued",
"fingerprint",
"rotated_at",
"last_fetched_at"
],
"type": "object"
},
"node_tags": {
"items": {
"type": "string"
},
"type": "array"
},
"node_user_id": {
"type": "integer"
},
"note": {
"type": [
"string",
"null"
]
},
"queue_seq": {
"type": [
"integer",
"null"
]
},
"suspended_reason": {
"type": [
"string",
"null"
]
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"suspended_reason",
"queue_seq",
"node_tags",
"device_bonus",
"node_user_id",
"credential",
"link",
"auto_renew_failures",
"access_version",
"note",
"updated_at",
"available_actions"
],
"type": "object"
}
]
},
"AdminSubscriptionCreate": {
"additionalProperties": false,
"properties": {
"activation": {
"default": "auto",
"enum": [
"auto",
"immediate",
"queued"
],
"type": "string"
},
"note": {
"maxLength": 500,
"type": [
"string",
"null"
]
},
"plan_id": {
"format": "uuid",
"type": "string"
},
"price_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"term": {
"$ref": "#/components/schemas/SubscriptionTerm"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"plan_id",
"reason"
],
"type": "object"
},
"AdminSubscriptionExtend": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"term": {
"$ref": "#/components/schemas/SubscriptionTerm"
},
"term_end_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
},
"AdminSubscriptionGrantTraffic": {
"additionalProperties": false,
"properties": {
"bytes": {
"description": "Bonus bytes for the current period",
"example": "10737418240",
"pattern": "^[1-9]\\d{0,18}$",
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"bytes",
"reason"
],
"type": "object"
},
"AdminSubscriptionLimits": {
"additionalProperties": false,
"properties": {
"device_limit": {
"description": "Base limit; null = unlimited",
"maximum": 10000,
"minimum": 0,
"type": [
"integer",
"null"
]
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"speed_limit_mbps": {
"maximum": 1000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"traffic_quota_bytes": {
"pattern": "^\\d{1,19}$",
"type": [
"string",
"null"
]
}
},
"required": [
"reason"
],
"type": "object"
},
"AdminSubscriptionPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/AdminSubscription"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"AdminSubscriptionReason": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
},
"AdminUser": {
"properties": {
"active_subscriptions": {
"type": "integer"
},
"available_actions": {
"description": "What the caller may do with this account (advisory; every command re-checks)",
"items": {
"enum": [
"update",
"activate",
"disable",
"ban",
"revoke_sessions",
"view_sensitive",
"reset_mfa"
],
"type": "string"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"email": {
"description": "Masked: a***@example.com",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"inviter": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"public_id": {
"type": "string"
}
},
"required": [
"id",
"public_id"
],
"type": [
"object",
"null"
]
},
"last_login_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"phone": {
"description": "Masked",
"type": [
"string",
"null"
]
},
"public_id": {
"type": "string"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"staff": {
"type": "boolean"
},
"status": {
"enum": [
"active",
"disabled",
"banned",
"deactivating",
"deleted"
],
"type": "string"
},
"two_factor_enabled": {
"type": "boolean"
}
},
"required": [
"id",
"public_id",
"email",
"phone",
"name",
"status",
"roles",
"staff",
"two_factor_enabled",
"created_at",
"last_login_at",
"inviter",
"active_subscriptions",
"available_actions"
],
"type": "object"
},
"AdminUserDetail": {
"allOf": [
{
"$ref": "#/components/schemas/AdminUser"
},
{
"properties": {
"email_verified": {
"type": "boolean"
},
"invited_via": {
"type": [
"string",
"null"
]
},
"locale": {
"type": "string"
},
"permissions": {
"description": "Expanded codes of the roles",
"items": {
"type": "string"
},
"type": "array"
},
"phone_verified": {
"type": "boolean"
},
"registered_via": {
"type": "string"
},
"sessions": {
"description": "Unexpired sessions",
"type": "integer"
},
"status_changed_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"status_reason": {
"type": [
"string",
"null"
]
},
"time_zone": {
"type": [
"string",
"null"
]
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"email_verified",
"phone_verified",
"locale",
"time_zone",
"status_reason",
"status_changed_at",
"registered_via",
"invited_via",
"updated_at",
"sessions",
"permissions"
],
"type": "object"
}
]
},
"AdminUserPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/AdminUser"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"AdminUserPatch": {
"additionalProperties": false,
"properties": {
"email": {
"description": "Becomes unverified until the user proves it",
"format": "email",
"maxLength": 254,
"type": "string"
},
"locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"name": {
"maxLength": 64,
"type": "string"
},
"time_zone": {
"maxLength": 64,
"minLength": 1,
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"AdminUserSensitive": {
"properties": {
"email": {
"type": "string"
},
"email_verified": {
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"phone_number": {
"type": [
"string",
"null"
]
},
"phone_verified": {
"type": "boolean"
}
},
"required": [
"id",
"email",
"email_verified",
"phone_number",
"phone_verified"
],
"type": "object"
},
"AdminWalletEntry": {
"allOf": [
{
"$ref": "#/components/schemas/WalletEntry"
},
{
"properties": {
"actor": {
"properties": {
"id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"system",
"user",
"staff"
],
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"memo": {
"type": [
"string",
"null"
]
},
"operation_key": {
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"operation_key",
"actor",
"memo"
],
"type": "object"
}
]
},
"AdminWalletEntryPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/AdminWalletEntry"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"AuditEvent": {
"properties": {
"action": {
"type": "string"
},
"actor": {
"properties": {
"id": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"user",
"staff",
"system",
"api_key",
"server"
],
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"category": {
"enum": [
"admin",
"security",
"billing",
"subscription",
"network",
"system",
"ops"
],
"type": "string"
},
"detail": {
"additionalProperties": {},
"description": "Redacted diff or event detail",
"type": [
"object",
"null"
]
},
"id": {
"type": "string"
},
"ip_masked": {
"description": "IPv4 /24 or IPv6 /48",
"type": [
"string",
"null"
]
},
"occurred_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"outcome": {
"enum": [
"success",
"denied",
"failed"
],
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"request_id": {
"type": [
"string",
"null"
]
},
"resource": {
"properties": {
"id": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
}
},
"required": [
"id",
"occurred_at",
"category",
"actor",
"action",
"resource",
"outcome",
"request_id",
"ip_masked",
"reason",
"detail"
],
"type": "object"
},
"AuditEventPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/AuditEvent"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"BulkReportExport": {
"properties": {
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"filters": {
"additionalProperties": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"bulk_report"
],
"type": "string"
},
"operator_id": {
"format": "uuid",
"type": "string"
},
"reason": {
"type": "string"
},
"row_count": {
"type": [
"integer",
"null"
]
},
"row_limit": {
"type": "integer"
},
"status": {
"enum": [
"pending",
"ready",
"failed",
"expired"
],
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"id",
"operator_id",
"reason",
"row_limit",
"filters",
"status",
"row_count",
"truncated",
"created_at",
"expires_at",
"kind"
],
"type": "object"
},
"CapChallenge": {
"properties": {
"challenge": {
"properties": {
"c": {
"description": "Number of puzzles",
"type": "integer"
},
"d": {
"description": "Difficulty (hex digits of the SHA-256 prefix)",
"type": "integer"
},
"s": {
"description": "Salt length",
"type": "integer"
}
},
"required": [
"c",
"s",
"d"
],
"type": "object"
},
"expires": {
"description": "Epoch milliseconds",
"type": "integer"
},
"token": {
"description": "Signed challenge (HS256 JWT)",
"type": "string"
}
},
"required": [
"challenge",
"token",
"expires"
],
"type": "object"
},
"CapPass": {
"properties": {
"expires": {
"description": "Epoch milliseconds",
"type": "integer"
},
"success": {
"enum": [
true
],
"type": "boolean"
},
"token": {
"description": "One-time pass token: send it in X-Captcha-Response",
"type": "string"
}
},
"required": [
"success",
"token",
"expires"
],
"type": "object"
},
"CapRedeemRequest": {
"properties": {
"solutions": {
"items": {
"type": "number"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
},
"token": {
"maxLength": 4096,
"minLength": 1,
"type": "string"
}
},
"required": [
"token",
"solutions"
],
"type": "object"
},
"CaptchaProviderTestRequest": {
"additionalProperties": false,
"properties": {
"provider": {
"enum": [
"turnstile",
"cap",
"image"
],
"type": "string"
}
},
"required": [
"provider"
],
"type": "object"
},
"CaptchaProviderTestResult": {
"properties": {
"detail": {
"type": "string"
},
"ok": {
"type": "boolean"
},
"provider": {
"type": "string"
}
},
"required": [
"provider",
"ok",
"detail"
],
"type": "object"
},
"CatalogI18n": {
"additionalProperties": {
"properties": {
"_meta": {
"description": "Read-only origin marker of the locale (machine translation, manual edit)",
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description_md": {
"type": "string"
},
"features": {
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"type": "string"
},
"subtitle": {
"type": "string"
}
},
"type": "object"
},
"type": "object"
},
"CatalogI18nInput": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {},
"description_md": {
"maxLength": 20000,
"type": "string"
},
"features": {
"items": {
"maxLength": 200,
"type": "string"
},
"maxItems": 20,
"type": "array"
},
"name": {
"maxLength": 100,
"type": "string"
},
"subtitle": {
"maxLength": 200,
"type": "string"
}
},
"type": "object"
},
"description": "Full map `{ \"<locale>\": { name, subtitle, description_md, features } }`; replaces the stored one",
"type": "object"
},
"CatalogMoney": {
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Amount in minor units as a decimal string",
"pattern": "^(0|[1-9]\\d{0,17})$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": "object"
},
"CatalogPlan": {
"properties": {
"code": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device_limit": {
"type": [
"integer",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"node_tags": {
"items": {
"type": "string"
},
"type": "array"
},
"per_user_limit": {
"type": [
"integer",
"null"
]
},
"product_id": {
"format": "uuid",
"type": "string"
},
"renewable_when_off_sale": {
"type": "boolean"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sort": {
"type": "integer"
},
"source_locale": {
"type": "string"
},
"speed_limit_mbps": {
"type": [
"integer",
"null"
]
},
"status": {
"enum": [
"draft",
"on_sale",
"off_sale",
"retired"
],
"type": "string"
},
"stock": {
"properties": {
"available": {
"type": [
"integer",
"null"
]
},
"reserved": {
"type": "integer"
},
"sold": {
"type": "integer"
},
"total": {
"description": "null = unlimited",
"type": [
"integer",
"null"
]
}
},
"required": [
"total",
"sold",
"reserved",
"available"
],
"type": "object"
},
"traffic_quota_bytes": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"version": {
"type": "integer"
},
"visible": {
"type": "boolean"
}
},
"required": [
"id",
"product_id",
"code",
"source_locale",
"i18n",
"status",
"visible",
"renewable_when_off_sale",
"traffic_quota_bytes",
"speed_limit_mbps",
"device_limit",
"reset_policy",
"reset_on_renewal",
"node_tags",
"stock",
"per_user_limit",
"sort",
"created_at",
"updated_at",
"version"
],
"type": "object"
},
"CatalogPlanCreate": {
"additionalProperties": false,
"properties": {
"code": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
"type": "string"
},
"device_limit": {
"description": "null = unlimited",
"maximum": 10000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18nInput"
},
"node_tags": {
"description": "Granted node tags (at least one)",
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 64,
"type": "array"
},
"per_user_limit": {
"maximum": 1000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"product_id": {
"format": "uuid",
"type": "string"
},
"renewable_when_off_sale": {
"type": "boolean"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"speed_limit_mbps": {
"description": "Mbps; null = unlimited",
"maximum": 1000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"stock_total": {
"description": "null = unlimited",
"maximum": 2147483647,
"minimum": 0,
"type": [
"integer",
"null"
]
},
"traffic_quota_bytes": {
"description": "Traffic quota in bytes as a decimal string; null = unlimited",
"pattern": "^[1-9]\\d{0,18}$",
"type": [
"string",
"null"
]
},
"visible": {
"type": "boolean"
}
},
"required": [
"product_id",
"code",
"source_locale",
"i18n",
"reset_policy",
"node_tags"
],
"type": "object"
},
"CatalogPlanDetail": {
"properties": {
"code": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device_limit": {
"type": [
"integer",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"node_tags": {
"items": {
"type": "string"
},
"type": "array"
},
"per_user_limit": {
"type": [
"integer",
"null"
]
},
"prices": {
"items": {
"$ref": "#/components/schemas/CatalogPrice"
},
"type": "array"
},
"product_id": {
"format": "uuid",
"type": "string"
},
"renewable_when_off_sale": {
"type": "boolean"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sort": {
"type": "integer"
},
"source_locale": {
"type": "string"
},
"speed_limit_mbps": {
"type": [
"integer",
"null"
]
},
"status": {
"enum": [
"draft",
"on_sale",
"off_sale",
"retired"
],
"type": "string"
},
"stock": {
"properties": {
"available": {
"type": [
"integer",
"null"
]
},
"reserved": {
"type": "integer"
},
"sold": {
"type": "integer"
},
"total": {
"description": "null = unlimited",
"type": [
"integer",
"null"
]
}
},
"required": [
"total",
"sold",
"reserved",
"available"
],
"type": "object"
},
"traffic_quota_bytes": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"version": {
"type": "integer"
},
"visible": {
"type": "boolean"
},
"warnings": {
"items": {
"$ref": "#/components/schemas/CatalogWarning"
},
"type": "array"
}
},
"required": [
"id",
"product_id",
"code",
"source_locale",
"i18n",
"status",
"visible",
"renewable_when_off_sale",
"traffic_quota_bytes",
"speed_limit_mbps",
"device_limit",
"reset_policy",
"reset_on_renewal",
"node_tags",
"stock",
"per_user_limit",
"sort",
"created_at",
"updated_at",
"version",
"prices",
"warnings"
],
"type": "object"
},
"CatalogPlanList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/CatalogPlan"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"CatalogPlanPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/CatalogPlan"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"CatalogPlanPatch": {
"additionalProperties": false,
"description": "Status, stock and order have their own endpoints",
"properties": {
"code": {
"pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
"type": "string"
},
"device_limit": {
"description": "null = unlimited",
"maximum": 10000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18nInput"
},
"node_tags": {
"description": "Granted node tags (at least one)",
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 64,
"type": "array"
},
"per_user_limit": {
"maximum": 1000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"product_id": {
"format": "uuid",
"type": "string"
},
"renewable_when_off_sale": {
"type": "boolean"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"speed_limit_mbps": {
"description": "Mbps; null = unlimited",
"maximum": 1000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"traffic_quota_bytes": {
"description": "Traffic quota in bytes as a decimal string; null = unlimited",
"pattern": "^[1-9]\\d{0,18}$",
"type": [
"string",
"null"
]
},
"visible": {
"type": "boolean"
}
},
"type": "object"
},
"CatalogPlanReorder": {
"additionalProperties": false,
"description": "Every plan of the product, once, in display order",
"properties": {
"plan_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
},
"product_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"product_id",
"plan_ids"
],
"type": "object"
},
"CatalogPlanSaved": {
"properties": {
"code": {
"type": "string"
},
"created_at": {
"type": "string"
},
"device_limit": {
"type": [
"integer",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"node_tags": {
"items": {
"type": "string"
},
"type": "array"
},
"per_user_limit": {
"type": [
"integer",
"null"
]
},
"product_id": {
"format": "uuid",
"type": "string"
},
"renewable_when_off_sale": {
"type": "boolean"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sort": {
"type": "integer"
},
"source_locale": {
"type": "string"
},
"speed_limit_mbps": {
"type": [
"integer",
"null"
]
},
"status": {
"enum": [
"draft",
"on_sale",
"off_sale",
"retired"
],
"type": "string"
},
"stock": {
"properties": {
"available": {
"type": [
"integer",
"null"
]
},
"reserved": {
"type": "integer"
},
"sold": {
"type": "integer"
},
"total": {
"description": "null = unlimited",
"type": [
"integer",
"null"
]
}
},
"required": [
"total",
"sold",
"reserved",
"available"
],
"type": "object"
},
"traffic_quota_bytes": {
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"version": {
"type": "integer"
},
"visible": {
"type": "boolean"
},
"warnings": {
"items": {
"$ref": "#/components/schemas/CatalogWarning"
},
"type": "array"
}
},
"required": [
"id",
"product_id",
"code",
"source_locale",
"i18n",
"status",
"visible",
"renewable_when_off_sale",
"traffic_quota_bytes",
"speed_limit_mbps",
"device_limit",
"reset_policy",
"reset_on_renewal",
"node_tags",
"stock",
"per_user_limit",
"sort",
"created_at",
"updated_at",
"version",
"warnings"
],
"type": "object"
},
"CatalogPlanStatus": {
"additionalProperties": false,
"properties": {
"renewable_when_off_sale": {
"type": "boolean"
},
"status": {
"enum": [
"draft",
"on_sale",
"off_sale",
"retired"
],
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
"CatalogPlanStock": {
"additionalProperties": false,
"properties": {
"stock_total": {
"description": "null = unlimited",
"maximum": 2147483647,
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"stock_total"
],
"type": "object"
},
"CatalogPrice": {
"properties": {
"amount": {
"$ref": "#/components/schemas/CatalogMoney"
},
"compare_at": {
"allOf": [
{
"$ref": "#/components/schemas/CatalogMoney"
},
{
"type": [
"object",
"null"
]
}
]
},
"created_at": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"period_count": {
"type": "integer"
},
"period_unit": {
"enum": [
"day",
"month",
"year",
"none"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
},
"sort": {
"type": "integer"
},
"status": {
"enum": [
"active",
"inactive"
],
"type": "string"
}
},
"required": [
"id",
"plan_id",
"period_unit",
"period_count",
"amount",
"compare_at",
"status",
"sort",
"created_at"
],
"type": "object"
},
"CatalogPriceCreate": {
"additionalProperties": false,
"properties": {
"amount": {
"$ref": "#/components/schemas/CatalogMoney"
},
"compare_at": {
"description": "Struck-through list price",
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Amount in minor units as a decimal string",
"pattern": "^(0|[1-9]\\d{0,17})$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": [
"object",
"null"
]
},
"period_count": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"period_unit": {
"description": "`none` = permanent (no term)",
"enum": [
"day",
"month",
"year",
"none"
],
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
}
},
"required": [
"period_unit",
"period_count",
"amount"
],
"type": "object"
},
"CatalogPriceList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/CatalogPrice"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"CatalogProduct": {
"properties": {
"created_at": {
"type": "string"
},
"group_key": {
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"slug": {
"type": "string"
},
"sort": {
"type": "integer"
},
"source_locale": {
"type": "string"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"updated_at": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"slug",
"group_key",
"source_locale",
"i18n",
"status",
"sort",
"created_at",
"updated_at",
"version"
],
"type": "object"
},
"CatalogProductCreate": {
"additionalProperties": false,
"properties": {
"group_key": {
"maxLength": 64,
"minLength": 1,
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18nInput"
},
"slug": {
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$",
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"status": {
"enum": [
"draft",
"active"
],
"type": "string"
}
},
"required": [
"slug",
"source_locale",
"i18n"
],
"type": "object"
},
"CatalogProductPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/CatalogProduct"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"CatalogProductPatch": {
"additionalProperties": false,
"properties": {
"group_key": {
"maxLength": 64,
"minLength": 1,
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CatalogI18nInput"
},
"slug": {
"pattern": "^[a-z0-9][a-z0-9-]{1,63}$",
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
}
},
"type": "object"
},
"CatalogWarning": {
"description": "Advice only: the save went through",
"properties": {
"code": {
"enum": [
"catalog.tags_without_nodes"
],
"type": "string"
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"code",
"tags"
],
"type": "object"
},
"CommerceChannel": {
"allOf": [
{
"$ref": "#/components/schemas/CommercePublicChannel"
},
{
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"secret_set": {
"type": "boolean"
},
"sort": {
"type": "integer"
},
"status": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"status",
"sort",
"config",
"secret_set",
"version"
],
"type": "object"
}
]
},
"CommerceOrder": {
"properties": {
"balance_applied_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"closed_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"created_at": {
"format": "date-time",
"type": "string"
},
"currency": {
"type": "string"
},
"discount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"fee_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"gift_applied_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"kind": {
"type": "string"
},
"order_no": {
"type": "string"
},
"origin": {
"type": "string"
},
"paid_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"refund_state": {
"type": "string"
},
"refunded_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"related": {
"properties": {
"order_no": {
"type": [
"string",
"null"
]
},
"subscription_status": {
"type": [
"string",
"null"
]
},
"user_email_masked": {
"type": "string"
},
"user_public_id": {
"type": "string"
}
},
"required": [
"user_public_id",
"user_email_masked",
"order_no",
"subscription_status"
],
"type": [
"object",
"null"
]
},
"result_subscription_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"snapshot": {
"additionalProperties": {},
"type": "object"
},
"status": {
"type": "string"
},
"subtotal_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"target_subscription_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"total_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"related",
"order_no",
"user_id",
"kind",
"origin",
"status",
"refund_state",
"currency",
"subtotal_minor",
"discount_minor",
"gift_applied_minor",
"balance_applied_minor",
"fee_minor",
"total_minor",
"paid_minor",
"refunded_minor",
"plan_id",
"target_subscription_id",
"result_subscription_id",
"snapshot",
"expires_at",
"paid_at",
"created_at",
"closed_at",
"version"
],
"type": "object"
},
"CommercePayment": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"attempt_no": {
"type": "integer"
},
"channel_id": {
"format": "uuid",
"type": "string"
},
"checkout": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"redirect"
],
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"type",
"url"
],
"type": "object"
},
{
"properties": {
"content": {
"type": "string"
},
"type": {
"enum": [
"qr"
],
"type": "string"
}
},
"required": [
"type",
"content"
],
"type": "object"
},
{
"properties": {
"fields": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"type": {
"enum": [
"form_post"
],
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"type",
"url",
"fields"
],
"type": "object"
},
{
"type": "null"
}
]
},
"created_at": {
"format": "date-time",
"type": "string"
},
"currency": {
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"fx_rate": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"order_id": {
"format": "uuid",
"type": "string"
},
"provider_payment_id": {
"type": [
"string",
"null"
]
},
"related": {
"properties": {
"order_no": {
"type": [
"string",
"null"
]
},
"subscription_status": {
"type": [
"string",
"null"
]
},
"user_email_masked": {
"type": "string"
},
"user_public_id": {
"type": "string"
}
},
"required": [
"user_public_id",
"user_email_masked",
"order_no",
"subscription_status"
],
"type": [
"object",
"null"
]
},
"status": {
"type": "string"
},
"succeeded_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"related",
"order_id",
"channel_id",
"attempt_no",
"status",
"currency",
"amount_minor",
"fx_rate",
"provider_payment_id",
"checkout",
"expires_at",
"succeeded_at",
"created_at",
"version"
],
"type": "object"
},
"CommercePaymentEvent": {
"properties": {
"channel_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"payment_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"provider_event_id": {
"type": [
"string",
"null"
]
},
"received_at": {
"format": "date-time",
"type": "string"
},
"reported_amount_minor": {
"type": [
"string",
"null"
]
},
"reported_currency": {
"type": [
"string",
"null"
]
},
"reported_status": {
"type": [
"string",
"null"
]
},
"result": {
"type": [
"string",
"null"
]
},
"signature_valid": {
"type": "boolean"
},
"source": {
"type": "string"
}
},
"required": [
"id",
"channel_id",
"payment_id",
"source",
"provider_event_id",
"signature_valid",
"reported_status",
"reported_amount_minor",
"reported_currency",
"result",
"received_at"
],
"type": "object"
},
"CommercePublicChannel": {
"properties": {
"currency": {
"type": "string"
},
"fee_bps": {
"type": "integer"
},
"fee_fixed_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"i18n": {
"additionalProperties": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"kind": {
"type": "string"
},
"max_amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"min_amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"source_locale": {
"type": "string"
}
},
"required": [
"id",
"kind",
"i18n",
"source_locale",
"currency",
"fee_bps",
"fee_fixed_minor",
"min_amount_minor",
"max_amount_minor"
],
"type": "object"
},
"CommerceQuote": {
"properties": {
"catalog": {
"additionalProperties": {},
"type": [
"object",
"null"
]
},
"coupons": {
"items": {
"properties": {
"applicable": {
"type": "boolean"
},
"code_id": {
"format": "uuid",
"type": "string"
},
"discount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"user_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"user_code_id",
"code_id",
"source",
"discount_minor",
"applicable",
"reason"
],
"type": "object"
},
"type": "array"
},
"currency": {
"type": "string"
},
"discount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"fee_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"fingerprint": {
"type": "string"
},
"gift_applied_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"subtotal_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"total_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"currency",
"subtotal_minor",
"discount_minor",
"gift_applied_minor",
"fee_minor",
"total_minor",
"fingerprint",
"coupons",
"catalog"
],
"type": "object"
},
"CommerceReceipt": {
"properties": {
"allocations": {
"items": {
"properties": {
"amount_minor": {
"type": "string"
},
"channel": {},
"payment_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"source": {
"enum": [
"gift",
"balance",
"online"
],
"type": "string"
}
},
"required": [
"source",
"amount_minor",
"payment_id"
],
"type": "object"
},
"type": "array"
},
"currency": {
"type": "string"
},
"item": {
"properties": {
"catalog": {},
"discount_minor": {
"type": "string"
},
"fee_minor": {
"type": "string"
},
"plan_name": {
"type": "string"
},
"quantity": {
"enum": [
1
],
"type": "number"
},
"unit_price_minor": {
"type": "string"
}
},
"required": [
"plan_name",
"quantity",
"unit_price_minor",
"discount_minor",
"fee_minor"
],
"type": "object"
},
"order_id": {
"format": "uuid",
"type": "string"
},
"order_no": {
"type": "string"
},
"order_status": {
"type": "string"
},
"paid_at": {
"format": "date-time",
"type": "string"
},
"status": {
"enum": [
"paid"
],
"type": "string"
},
"total_minor": {
"type": "string"
}
},
"required": [
"order_id",
"order_no",
"currency",
"status",
"paid_at",
"order_status",
"item",
"total_minor",
"allocations"
],
"type": "object"
},
"CommerceRefund": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"currency": {
"type": "string"
},
"entitlement_action": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"method": {
"type": "string"
},
"order_id": {
"format": "uuid",
"type": "string"
},
"payment_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"reason": {
"type": "string"
},
"refund_no": {
"type": "string"
},
"related": {
"properties": {
"order_no": {
"type": [
"string",
"null"
]
},
"subscription_status": {
"type": [
"string",
"null"
]
},
"user_email_masked": {
"type": "string"
},
"user_public_id": {
"type": "string"
}
},
"required": [
"user_public_id",
"user_email_masked",
"order_no",
"subscription_status"
],
"type": [
"object",
"null"
]
},
"status": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"related",
"refund_no",
"order_id",
"payment_id",
"method",
"amount_minor",
"currency",
"status",
"reason",
"entitlement_action",
"created_at",
"version"
],
"type": "object"
},
"Coupon": {
"properties": {
"code": {
"type": [
"string",
"null"
]
},
"counters": {
"description": "issued: issued coupons; reserved / redeemed: public code uses",
"properties": {
"issued": {
"type": "integer"
},
"redeemed": {
"type": "integer"
},
"reserved": {
"type": "integer"
}
},
"required": [
"issued",
"reserved",
"redeemed"
],
"type": "object"
},
"created_at": {
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"discount": {
"$ref": "#/components/schemas/CouponDiscount"
},
"distribution": {
"enum": [
"public",
"issued"
],
"type": "string"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CouponI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"type": [
"integer",
"null"
]
},
"name": {
"type": "string"
},
"per_user_limit": {
"type": "integer"
},
"recurring": {
"$ref": "#/components/schemas/CouponRecurring"
},
"scope": {
"$ref": "#/components/schemas/CouponScope"
},
"source_locale": {
"type": "string"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"disabled"
],
"type": "string"
},
"valid_days": {
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"name",
"distribution",
"code",
"status",
"source_locale",
"i18n",
"discount",
"scope",
"recurring",
"valid_days",
"max_redemptions",
"per_user_limit",
"starts_at",
"ends_at",
"counters",
"created_by",
"created_at",
"version"
],
"type": "object"
},
"CouponCreate": {
"additionalProperties": false,
"properties": {
"code": {
"description": "Public coupons only: the text typed at checkout (stored upper-case)",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{3,31}$",
"type": [
"string",
"null"
]
},
"discount": {
"$ref": "#/components/schemas/CouponDiscountInput"
},
"distribution": {
"enum": [
"public",
"issued"
],
"type": "string"
},
"ends_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CouponI18nInput"
},
"max_redemptions": {
"description": "Public: total uses; issued: coupons issued; null = unlimited",
"maximum": 100000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"name": {
"description": "Staff-facing name",
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"per_user_limit": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"recurring": {
"$ref": "#/components/schemas/CouponRecurringInput"
},
"scope": {
"$ref": "#/components/schemas/CouponScopeInput"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"starts_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"disabled"
],
"type": "string"
},
"valid_days": {
"description": "Issued coupons: days from issue",
"maximum": 3650,
"minimum": 1,
"type": [
"integer",
"null"
]
}
},
"required": [
"name",
"distribution",
"source_locale",
"i18n",
"discount"
],
"type": "object"
},
"CouponDetail": {
"properties": {
"code": {
"type": [
"string",
"null"
]
},
"counters": {
"description": "issued: issued coupons; reserved / redeemed: public code uses",
"properties": {
"issued": {
"type": "integer"
},
"redeemed": {
"type": "integer"
},
"reserved": {
"type": "integer"
}
},
"required": [
"issued",
"reserved",
"redeemed"
],
"type": "object"
},
"created_at": {
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"discount": {
"$ref": "#/components/schemas/CouponDiscount"
},
"distribution": {
"enum": [
"public",
"issued"
],
"type": "string"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CouponI18n"
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"type": [
"integer",
"null"
]
},
"name": {
"type": "string"
},
"per_user_limit": {
"type": "integer"
},
"recurring": {
"$ref": "#/components/schemas/CouponRecurring"
},
"scope": {
"$ref": "#/components/schemas/CouponScope"
},
"source_locale": {
"type": "string"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"disabled"
],
"type": "string"
},
"usage": {
"description": "Coupons of this definition in wallets, held by open orders, and used",
"properties": {
"available": {
"type": "integer"
},
"consumed": {
"type": "integer"
},
"reserved": {
"type": "integer"
}
},
"required": [
"available",
"reserved",
"consumed"
],
"type": "object"
},
"valid_days": {
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"name",
"distribution",
"code",
"status",
"source_locale",
"i18n",
"discount",
"scope",
"recurring",
"valid_days",
"max_redemptions",
"per_user_limit",
"starts_at",
"ends_at",
"counters",
"created_by",
"created_at",
"version",
"usage"
],
"type": "object"
},
"CouponDiscount": {
"oneOf": [
{
"properties": {
"max_discount": {
"$ref": "#/components/schemas/GrowthMoney"
},
"percent_bps": {
"type": "integer"
},
"type": {
"enum": [
"percent"
],
"type": "string"
}
},
"required": [
"type",
"percent_bps",
"max_discount"
],
"type": "object"
},
{
"properties": {
"amount": {
"$ref": "#/components/schemas/GrowthMoney"
},
"type": {
"enum": [
"amount"
],
"type": "string"
}
},
"required": [
"type",
"amount"
],
"type": "object"
}
]
},
"CouponDiscountInput": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"max_discount": {
"description": "Cap of the discount; null = none",
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Amount in minor units as a decimal string",
"pattern": "^(0|[1-9]\\d{0,17})$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": [
"object",
"null"
]
},
"percent_bps": {
"description": "1000 = 10 % off",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"type": {
"enum": [
"percent"
],
"type": "string"
}
},
"required": [
"type",
"percent_bps"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"amount": {
"$ref": "#/components/schemas/GrowthMoney"
},
"type": {
"enum": [
"amount"
],
"type": "string"
}
},
"required": [
"type",
"amount"
],
"type": "object"
}
]
},
"CouponI18n": {
"additionalProperties": {
"properties": {
"_meta": {
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
},
"type": "object"
},
"CouponI18nInput": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {},
"description": {
"maxLength": 1000,
"type": "string"
},
"title": {
"maxLength": 100,
"type": "string"
}
},
"type": "object"
},
"description": "Full map `{ \"<locale>\": { title, description } }`; replaces the stored one",
"type": "object"
},
"CouponIssue": {
"additionalProperties": false,
"properties": {
"user_ids": {
"description": "At most 100 users; larger audiences go through a bulk operation",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
},
"required": [
"user_ids"
],
"type": "object"
},
"CouponIssueResult": {
"description": "Batch result; partial success is not an error",
"properties": {
"results": {
"items": {
"properties": {
"error": {
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
},
"id": {
"description": "The issued coupon",
"format": "uuid",
"type": "string"
},
"index": {
"type": "integer"
},
"status": {
"enum": [
"succeeded",
"failed"
],
"type": "string"
}
},
"required": [
"index",
"status"
],
"type": "object"
},
"type": "array"
},
"summary": {
"properties": {
"failed": {
"type": "integer"
},
"succeeded": {
"type": "integer"
}
},
"required": [
"succeeded",
"failed"
],
"type": "object"
}
},
"required": [
"results",
"summary"
],
"type": "object"
},
"CouponPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/Coupon"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"CouponPatch": {
"additionalProperties": false,
"properties": {
"code": {
"description": "Public coupons only",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{3,31}$",
"type": "string"
},
"discount": {
"$ref": "#/components/schemas/CouponDiscountInput"
},
"ends_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"i18n": {
"$ref": "#/components/schemas/CouponI18nInput"
},
"max_redemptions": {
"description": "Public: total uses; issued: coupons issued; null = unlimited",
"maximum": 100000000,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"name": {
"description": "Staff-facing name",
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"per_user_limit": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"recurring": {
"$ref": "#/components/schemas/CouponRecurringInput"
},
"scope": {
"allOf": [
{
"$ref": "#/components/schemas/CouponScopeInput"
},
{
"description": "Replaces the whole scope"
}
]
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"starts_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"description": "`disabled` stops new issue and public use",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"valid_days": {
"description": "Issued coupons: days from issue",
"maximum": 3650,
"minimum": 1,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"CouponPeriod": {
"additionalProperties": false,
"description": "A price option period, e.g. { unit: \"month\", count: 3 }",
"properties": {
"count": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"unit": {
"enum": [
"day",
"month",
"year",
"none"
],
"type": "string"
}
},
"required": [
"unit",
"count"
],
"type": "object"
},
"CouponRecurring": {
"properties": {
"mode": {
"enum": [
"once",
"periods",
"forever"
],
"type": "string"
},
"periods": {
"type": [
"integer",
"null"
]
}
},
"required": [
"mode",
"periods"
],
"type": "object"
},
"CouponRecurringInput": {
"additionalProperties": false,
"description": "once = this order only; periods = the first N billing periods; forever = while subscribed",
"properties": {
"mode": {
"enum": [
"once",
"periods",
"forever"
],
"type": "string"
},
"periods": {
"description": "`periods` mode: billing periods including the first one",
"maximum": 120,
"minimum": 2,
"type": [
"integer",
"null"
]
}
},
"required": [
"mode"
],
"type": "object"
},
"CouponScope": {
"properties": {
"first_order_only": {
"type": "boolean"
},
"min_subtotal": {
"$ref": "#/components/schemas/GrowthMoney"
},
"order_kinds": {
"items": {
"enum": [
"purchase",
"renewal",
"traffic_reset",
"plan_change"
],
"type": "string"
},
"type": "array"
},
"periods": {
"items": {
"properties": {
"count": {
"type": "integer"
},
"unit": {
"enum": [
"day",
"month",
"year",
"none"
],
"type": "string"
}
},
"required": [
"unit",
"count"
],
"type": "object"
},
"type": [
"array",
"null"
]
},
"plan_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"type": [
"array",
"null"
]
}
},
"required": [
"plan_ids",
"periods",
"order_kinds",
"min_subtotal",
"first_order_only"
],
"type": "object"
},
"CouponScopeInput": {
"additionalProperties": false,
"properties": {
"first_order_only": {
"type": "boolean"
},
"min_subtotal": {
"$ref": "#/components/schemas/GrowthMoney"
},
"order_kinds": {
"description": "Default purchase and renewal; top-ups are never discounted",
"items": {
"enum": [
"purchase",
"renewal",
"traffic_reset",
"plan_change"
],
"type": "string"
},
"minItems": 1,
"type": "array"
},
"periods": {
"description": "null = every period",
"items": {
"$ref": "#/components/schemas/CouponPeriod"
},
"maxItems": 20,
"minItems": 1,
"type": [
"array",
"null"
]
},
"plan_ids": {
"description": "null = every plan",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 200,
"minItems": 1,
"type": [
"array",
"null"
]
}
},
"type": "object"
},
"File": {
"properties": {
"content_type": {
"description": "Canonical type from content sniffing",
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"deleted_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"expires_at": {
"description": "Upload or verification deadline, restore deadline of a deleted file, export expiry",
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"filename": {
"type": "string"
},
"id": {
"type": "string"
},
"meta": {
"additionalProperties": {},
"description": "image {width, height}; package {platform, arch, version}",
"type": "object"
},
"object_key": {
"type": "string"
},
"owner_id": {
"type": [
"string",
"null"
]
},
"owner_type": {
"enum": [
"user",
"staff",
"system"
],
"type": "string"
},
"purpose": {
"enum": [
"site_asset",
"image",
"package",
"ticket_attachment",
"receipt",
"export"
],
"type": "string"
},
"ready_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"reject_reason": {
"type": [
"string",
"null"
]
},
"sha256": {
"description": "SHA-256, lower-case hex",
"pattern": "^[0-9a-f]{64}$",
"type": [
"string",
"null"
]
},
"size": {
"description": "Bytes as a decimal string",
"example": "1048576",
"pattern": "^\\d{1,15}$",
"type": "string"
},
"status": {
"enum": [
"uploading",
"verifying",
"ready",
"rejected",
"deleted"
],
"type": "string"
},
"upload": {
"$ref": "#/components/schemas/FileUploadState"
},
"url": {
"description": "Public URL, or the authenticated download route of a private file",
"type": "string"
},
"visibility": {
"enum": [
"public",
"private"
],
"type": "string"
}
},
"required": [
"id",
"purpose",
"visibility",
"status",
"filename",
"content_type",
"size",
"sha256",
"url",
"object_key",
"meta",
"reject_reason",
"owner_type",
"owner_id",
"created_at",
"ready_at",
"deleted_at",
"expires_at",
"upload"
],
"type": "object"
},
"FileDetail": {
"allOf": [
{
"$ref": "#/components/schemas/File"
},
{
"properties": {
"references": {
"description": "Possible reference locations",
"items": {
"properties": {
"location": {
"type": "string"
},
"source": {
"type": "string"
}
},
"required": [
"source",
"location"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"references"
],
"type": "object"
}
]
},
"FilePage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/File"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"FilePartResult": {
"properties": {
"etag": {
"type": "string"
},
"part_number": {
"type": "integer"
},
"received_parts": {
"type": "integer"
},
"size": {
"description": "Bytes as a decimal string",
"example": "1048576",
"pattern": "^\\d{1,15}$",
"type": "string"
}
},
"required": [
"part_number",
"etag",
"size",
"received_parts"
],
"type": "object"
},
"FileUploadComplete": {
"properties": {
"parts": {
"description": "Parts as recorded by the client; when sent they must match the received parts",
"items": {
"properties": {
"etag": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"part_number": {
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
},
"required": [
"part_number",
"etag"
],
"type": "object"
},
"maxItems": 10000,
"type": "array"
}
},
"type": "object"
},
"FileUploadCreate": {
"properties": {
"content_type": {
"description": "Declared MIME type (pre-check only)",
"maxLength": 255,
"type": [
"string",
"null"
]
},
"filename": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
},
"purpose": {
"enum": [
"site_asset",
"image",
"package",
"ticket_attachment",
"receipt"
],
"type": "string"
},
"sha256": {
"description": "SHA-256 of the whole file, verified on completion",
"pattern": "^[0-9a-f]{64}$",
"type": [
"string",
"null"
]
},
"size": {
"description": "Bytes as a decimal string",
"example": "1048576",
"pattern": "^\\d{1,15}$",
"type": "string"
}
},
"required": [
"purpose",
"filename",
"size"
],
"type": "object"
},
"FileUploadState": {
"properties": {
"expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"part_count": {
"type": "integer"
},
"part_size": {
"description": "null: single part (`parts/1` carries the whole file)",
"example": "1048576",
"pattern": "^\\d{1,15}$",
"type": [
"string",
"null"
]
},
"received_parts": {
"description": "Parts stored so far; a resuming client sends only the missing ones",
"items": {
"properties": {
"etag": {
"type": "string"
},
"part_number": {
"type": "integer"
},
"size": {
"description": "Bytes as a decimal string",
"example": "1048576",
"pattern": "^\\d{1,15}$",
"type": "string"
}
},
"required": [
"part_number",
"etag",
"size"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"part_size",
"part_count",
"received_parts",
"expires_at"
],
"type": [
"object",
"null"
]
},
"GrowthMoney": {
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Amount in minor units as a decimal string",
"pattern": "^(0|[1-9]\\d{0,17})$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": [
"object",
"null"
]
},
"HardwareDevicePolicy": {
"properties": {
"mode": {
"enum": [
"ip",
"hwid",
"both"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"mode",
"version"
],
"type": "object"
},
"HardwareDevices": {
"allOf": [
{
"$ref": "#/components/schemas/HardwareDevicePolicy"
},
{
"properties": {
"items": {
"items": {
"properties": {
"device_key": {
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"first_seen_at": {
"format": "date-time",
"type": "string"
},
"hwid_masked": {
"type": "string"
},
"last_seen_at": {
"format": "date-time",
"type": "string"
},
"limited": {
"type": "boolean"
},
"reason": {
"type": [
"string",
"null"
]
},
"revoked_until": {
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"device_key",
"hwid_masked",
"limited",
"reason",
"first_seen_at",
"last_seen_at",
"expires_at",
"revoked_until"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
]
},
"Health": {
"properties": {
"status": {
"enum": [
"ok"
],
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
"InboxMessage": {
"properties": {
"body_md": {
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"read_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
}
},
"required": [
"id",
"title",
"body_md",
"read_at",
"created_at"
],
"type": "object"
},
"InboxUnreadCount": {
"properties": {
"unread_count": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"unread_count"
],
"type": "object"
},
"InstallRequest": {
"additionalProperties": false,
"properties": {
"install_token": {
"default": "",
"maxLength": 1024,
"type": "string"
},
"root": {
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"maxLength": 254,
"type": "string"
},
"locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"password": {
"maxLength": 128,
"minLength": 8,
"type": "string"
}
},
"required": [
"email",
"password",
"name"
],
"type": "object"
},
"site": {
"additionalProperties": false,
"properties": {
"currency": {
"default": "USD",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"name": {
"type": "string"
},
"source_locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"timezone": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"timezone"
],
"type": "object"
}
},
"required": [
"site",
"root"
],
"type": "object"
},
"InstallResponse": {
"properties": {
"completed_at": {
"type": "string"
},
"root_user_id": {
"type": "string"
},
"state": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"state",
"completed_at",
"root_user_id"
],
"type": "object"
},
"InstallStatus": {
"properties": {
"completed_at": {
"description": "ISO-8601; null while pending",
"type": [
"string",
"null"
]
},
"state": {
"enum": [
"pending",
"completed"
],
"type": "string"
},
"wizard": {
"description": "What the wizard form needs; null once installed",
"properties": {
"defaults": {
"properties": {
"currency": {
"type": "string"
},
"site_name": {
"type": "string"
},
"source_locale": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"site_name",
"currency",
"timezone",
"source_locale"
],
"type": "object"
},
"master_keys_configured": {
"type": "boolean"
},
"password_policy": {
"properties": {
"max_length": {
"type": "integer"
},
"min_length": {
"type": "integer"
}
},
"required": [
"min_length",
"max_length"
],
"type": "object"
}
},
"required": [
"defaults",
"password_policy",
"master_keys_configured"
],
"type": [
"object",
"null"
]
}
},
"required": [
"state",
"completed_at",
"wizard"
],
"type": "object"
},
"Invitation": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"email": {
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"inviter_id": {
"format": "uuid",
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"enum": [
"pending",
"accepted",
"rejected",
"canceled"
],
"type": "string"
}
},
"required": [
"id",
"email",
"role",
"status",
"expires_at",
"inviter_id",
"created_at"
],
"type": "object"
},
"InvitationAccepted": {
"properties": {
"changed": {
"type": "boolean"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"roles",
"changed"
],
"type": "object"
},
"InvitationCreate": {
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"maxLength": 254,
"type": "string"
},
"role": {
"default": "customer",
"pattern": "^[a-z][a-z0-9_]{1,31}$",
"type": "string"
}
},
"required": [
"email"
],
"type": "object"
},
"InvitationList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/Invitation"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"Job": {
"properties": {
"attempts": {
"type": "integer"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"dedupe_key": {
"type": [
"string",
"null"
]
},
"finished_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"last_error": {
"type": [
"string",
"null"
]
},
"lease_expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"max_attempts": {
"type": "integer"
},
"priority": {
"type": "integer"
},
"queue": {
"enum": [
"default",
"heavy"
],
"type": "string"
},
"request_id": {
"type": [
"string",
"null"
]
},
"run_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"succeeded",
"dead",
"cancelled"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"kind",
"queue",
"status",
"priority",
"attempts",
"max_attempts",
"run_at",
"dedupe_key",
"last_error",
"request_id",
"lease_expires_at",
"created_at",
"updated_at",
"finished_at"
],
"type": "object"
},
"JobDetail": {
"description": "Payload redacted by the job kind",
"properties": {
"attempts": {
"type": "integer"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"dedupe_key": {
"type": [
"string",
"null"
]
},
"finished_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"last_error": {
"type": [
"string",
"null"
]
},
"lease_expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"max_attempts": {
"type": "integer"
},
"payload": {
"description": "JSON value"
},
"priority": {
"type": "integer"
},
"progress": {
"description": "JSON value"
},
"queue": {
"enum": [
"default",
"heavy"
],
"type": "string"
},
"request_id": {
"type": [
"string",
"null"
]
},
"run_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"succeeded",
"dead",
"cancelled"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"kind",
"queue",
"status",
"priority",
"attempts",
"max_attempts",
"run_at",
"dedupe_key",
"last_error",
"request_id",
"lease_expires_at",
"created_at",
"updated_at",
"finished_at"
],
"type": "object"
},
"JobPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/Job"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"JobReplayResult": {
"properties": {
"job": {
"$ref": "#/components/schemas/JobDetail"
},
"outcome": {
"description": "`superseded`: the dedupe key already had a pending job, so this job was cancelled instead",
"enum": [
"requeued",
"superseded"
],
"type": "string"
}
},
"required": [
"outcome",
"job"
],
"type": "object"
},
"JobStats": {
"properties": {
"kinds": {
"items": {
"properties": {
"dead": {
"minimum": 0,
"type": "integer"
},
"failures_1h": {
"minimum": 0,
"type": "integer"
},
"kind": {
"type": "string"
},
"oldest_due_seconds": {
"minimum": 0,
"type": "number"
},
"pending": {
"minimum": 0,
"type": "integer"
},
"queue": {
"enum": [
"default",
"heavy"
],
"type": "string"
},
"running": {
"minimum": 0,
"type": "integer"
},
"superseded_1h": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"queue",
"pending",
"oldest_due_seconds",
"running",
"failures_1h",
"dead",
"superseded_1h",
"kind"
],
"type": "object"
},
"type": "array"
},
"queues": {
"items": {
"properties": {
"dead": {
"minimum": 0,
"type": "integer"
},
"failures_1h": {
"minimum": 0,
"type": "integer"
},
"oldest_due_seconds": {
"minimum": 0,
"type": "number"
},
"pending": {
"minimum": 0,
"type": "integer"
},
"queue": {
"enum": [
"default",
"heavy"
],
"type": "string"
},
"running": {
"minimum": 0,
"type": "integer"
},
"superseded_1h": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"queue",
"pending",
"oldest_due_seconds",
"running",
"failures_1h",
"dead",
"superseded_1h"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"queues",
"kinds"
],
"type": "object"
},
"LedgerMoney": {
"properties": {
"currency": {
"example": "USD",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Signed integer in minor units",
"example": "1999",
"pattern": "^-?\\d+$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": "object"
},
"MaintenanceState": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"retry_after_seconds": {
"maximum": 86400,
"minimum": 1,
"type": "integer"
},
"version": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"enabled",
"retry_after_seconds",
"version"
],
"type": "object"
},
"MasterKeyInventory": {
"properties": {
"active_version": {
"type": "integer"
},
"auth_wrapped_records": {
"type": "integer"
},
"hardware_live_versions": {
"additionalProperties": {
"type": "number"
},
"type": "object"
},
"hardware_presence_available": {
"type": "boolean"
},
"hardware_versions": {
"additionalProperties": {
"type": "number"
},
"type": "object"
},
"malformed": {
"type": "integer"
},
"old_ciphertexts": {
"type": "integer"
},
"old_version": {
"type": [
"integer",
"null"
]
},
"retirement_safe": {
"type": "boolean"
},
"sources": {
"additionalProperties": {
"type": "number"
},
"type": "object"
},
"versions": {
"additionalProperties": {
"additionalProperties": {
"type": "number"
},
"type": "object"
},
"type": "object"
}
},
"required": [
"active_version",
"versions",
"sources",
"malformed",
"hardware_versions",
"hardware_presence_available",
"hardware_live_versions",
"auth_wrapped_records",
"old_version",
"old_ciphertexts",
"retirement_safe"
],
"type": "object"
},
"Me": {
"properties": {
"capabilities": {
"description": "me.* capabilities of all roles",
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"email": {
"type": "string"
},
"email_verified": {
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"locale": {
"type": "string"
},
"name": {
"type": "string"
},
"public_id": {
"type": "string"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"staff": {
"type": "boolean"
},
"status": {
"type": "string"
},
"time_zone": {
"type": [
"string",
"null"
]
},
"two_factor_enabled": {
"type": "boolean"
}
},
"required": [
"id",
"public_id",
"email",
"email_verified",
"name",
"locale",
"time_zone",
"status",
"two_factor_enabled",
"roles",
"staff",
"capabilities",
"created_at"
],
"type": "object"
},
"MePatch": {
"additionalProperties": false,
"properties": {
"locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"name": {
"maxLength": 64,
"type": "string"
},
"time_zone": {
"maxLength": 64,
"minLength": 1,
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"MyCoupon": {
"properties": {
"code": {
"description": "The public code text, for code uses",
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"discount": {
"$ref": "#/components/schemas/CouponDiscount"
},
"id": {
"format": "uuid",
"type": "string"
},
"recurring": {
"$ref": "#/components/schemas/UserCouponRecurring"
},
"reserved_order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"scope": {
"$ref": "#/components/schemas/CouponScope"
},
"source": {
"enum": [
"checkout",
"admin",
"bulk",
"registration",
"referral"
],
"type": "string"
},
"status": {
"enum": [
"available",
"reserved",
"consumed",
"released",
"reversed",
"expired",
"revoked"
],
"type": "string"
},
"subscription_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"valid_from": {
"type": [
"string",
"null"
]
},
"valid_until": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"status",
"source",
"discount",
"scope",
"recurring",
"valid_from",
"valid_until",
"reserved_order_id",
"subscription_id",
"created_at",
"title",
"description",
"code"
],
"type": "object"
},
"MyCouponPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/MyCoupon"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"MySubscription": {
"properties": {
"auto_renew": {
"properties": {
"enabled": {
"type": "boolean"
},
"next_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"price_id": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"enabled",
"price_id",
"next_at"
],
"type": "object"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"deliverable": {
"description": "Whether the subscription is active, within its validity window and below its traffic quota",
"type": "boolean"
},
"end_reason": {
"type": [
"string",
"null"
]
},
"ended_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"entitlement": {
"properties": {
"device_limit": {
"description": "Effective limit (bonuses included); null = unlimited",
"type": [
"integer",
"null"
]
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"speed_limit_mbps": {
"type": [
"integer",
"null"
]
},
"traffic_quota_bytes": {
"description": "null = unlimited",
"example": "107374182400",
"pattern": "^\\d{1,19}$",
"type": [
"string",
"null"
]
}
},
"required": [
"traffic_quota_bytes",
"device_limit",
"speed_limit_mbps",
"reset_policy",
"reset_on_renewal"
],
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"plan": {
"properties": {
"code": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"names": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"price": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"period_count": {
"type": "integer"
},
"period_unit": {
"type": "string"
},
"perpetual": {
"type": "boolean"
}
},
"required": [
"id",
"period_unit",
"period_count",
"perpetual"
],
"type": [
"object",
"null"
]
},
"product_name": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"code",
"name",
"names",
"product_name",
"version",
"price"
],
"type": "object"
},
"public_id": {
"type": "string"
},
"queue": {
"properties": {
"expected_start_at": {
"description": "null: after a permanent subscription (never)",
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"position": {
"type": "integer"
}
},
"required": [
"position",
"expected_start_at"
],
"type": [
"object",
"null"
]
},
"source": {
"enum": [
"order",
"code",
"admin",
"trial",
"apple"
],
"type": "string"
},
"status": {
"enum": [
"scheduled",
"active",
"exhausted",
"expired",
"cancelled",
"refunded"
],
"type": "string"
},
"suspended": {
"type": "boolean"
},
"term": {
"properties": {
"anchor_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"end_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"perpetual": {
"type": "boolean"
},
"start_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"start_at",
"end_at",
"perpetual",
"anchor_at"
],
"type": "object"
},
"usage": {
"properties": {
"bonus_bytes": {
"description": "Bytes as a decimal string",
"example": "107374182400",
"pattern": "^\\d{1,19}$",
"type": "string"
},
"download_bytes": {
"description": "Bytes as a decimal string",
"example": "107374182400",
"pattern": "^\\d{1,19}$",
"type": "string"
},
"exhausted_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"period_end_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"period_seq": {
"type": "integer"
},
"period_start_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"upload_bytes": {
"description": "Bytes as a decimal string",
"example": "107374182400",
"pattern": "^\\d{1,19}$",
"type": "string"
},
"used_bytes": {
"description": "Bytes as a decimal string",
"example": "107374182400",
"pattern": "^\\d{1,19}$",
"type": "string"
}
},
"required": [
"period_seq",
"period_start_at",
"period_end_at",
"upload_bytes",
"download_bytes",
"used_bytes",
"bonus_bytes",
"exhausted_at"
],
"type": "object"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"public_id",
"status",
"suspended",
"deliverable",
"source",
"plan",
"term",
"entitlement",
"usage",
"queue",
"auto_renew",
"ended_at",
"end_reason",
"created_at",
"version"
],
"type": "object"
},
"MySubscriptionPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/MySubscription"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NetworkAgentToken": {
"properties": {
"expires_at": {
"description": "Enrollment: token expiry. Rotation: end of the old token grace",
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"server_id": {
"format": "uuid",
"type": "string"
},
"token": {
"description": "Shown once; null on an idempotent replay",
"type": [
"string",
"null"
]
}
},
"required": [
"server_id",
"token",
"expires_at"
],
"type": "object"
},
"NetworkInbound": {
"properties": {
"billing_multiplier": {
"example": "1.5000",
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"credential": {
"additionalProperties": {},
"description": "Credential form users of this inbound need (derived per protocol from node_secret)",
"properties": {
"kind": {
"enum": [
"uuid",
"password",
"uuid_password",
"username_password",
"ss2022_key"
],
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"node_count": {
"type": "integer"
},
"params": {
"additionalProperties": {},
"description": "Public parameters; stored secrets appear as { \"set\": true }",
"type": "object"
},
"port": {
"type": "integer"
},
"protocol": {
"enum": [
"vmess",
"vless",
"trojan",
"shadowsocks",
"hysteria2",
"tuic",
"anytls",
"naive",
"socks",
"http"
],
"type": "string"
},
"secret_paths": {
"items": {
"type": "string"
},
"type": "array"
},
"server_id": {
"format": "uuid",
"type": "string"
},
"status": {
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"transport_layer": {
"enum": [
"tcp",
"udp",
"tcp_udp"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"server_id",
"protocol",
"port",
"transport_layer",
"status",
"billing_multiplier",
"params",
"secret_paths",
"credential",
"node_count",
"created_at",
"updated_at",
"version"
],
"type": "object"
},
"NetworkInboundInput": {
"additionalProperties": false,
"properties": {
"billing_multiplier": {
"default": "1",
"pattern": "^\\d{1,4}(\\.\\d{1,4})?$",
"type": "string"
},
"params": {
"additionalProperties": {},
"default": {},
"description": "Protocol parameters `{ transport?, security?, settings }` (GET /admin/network/protocols has the JSON Schema per protocol). Secrets: omit or send { \"set\": true } to keep, null to clear.",
"type": "object"
},
"port": {
"maximum": 65535,
"minimum": 1,
"type": "integer"
},
"protocol": {
"enum": [
"vmess",
"vless",
"trojan",
"shadowsocks",
"hysteria2",
"tuic",
"anytls",
"naive",
"socks",
"http"
],
"type": "string"
},
"status": {
"default": "enabled",
"enum": [
"enabled",
"disabled"
],
"type": "string"
},
"transport_layer": {
"description": "Default: the protocol's first allowed layer (e.g. udp for hysteria2)",
"enum": [
"tcp",
"udp",
"tcp_udp"
],
"type": "string"
}
},
"required": [
"protocol",
"port"
],
"type": "object"
},
"NetworkInboundList": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/NetworkInbound"
},
"type": "array"
},
"next_cursor": {
"type": "null"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NetworkInboundSecrets": {
"properties": {
"inbound_id": {
"format": "uuid",
"type": "string"
},
"secrets": {
"additionalProperties": {
"type": "string"
},
"type": "object"
}
},
"required": [
"inbound_id",
"secrets"
],
"type": "object"
},
"NetworkInboundStatusInput": {
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"enabled",
"disabled"
],
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
},
"NetworkNode": {
"properties": {
"address_family": {
"enum": [
"ipv4",
"ipv6",
"dual"
],
"type": "string"
},
"client_overrides": {
"additionalProperties": {},
"type": "object"
},
"connect_host": {
"type": "string"
},
"connect_port": {
"type": [
"integer",
"null"
]
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"inbound_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"direct",
"relay",
"cdn"
],
"type": "string"
},
"name": {
"type": "string"
},
"name_i18n": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"port": {
"description": "connect_port, else the inbound port",
"type": "integer"
},
"protocol": {
"enum": [
"vmess",
"vless",
"trojan",
"shadowsocks",
"hysteria2",
"tuic",
"anytls",
"naive",
"socks",
"http"
],
"type": "string"
},
"region_code": {
"type": [
"string",
"null"
]
},
"server_id": {
"format": "uuid",
"type": "string"
},
"server_name": {
"type": "string"
},
"sort": {
"type": "integer"
},
"system_tags": {
"description": "Derived; filters and groups only, never authorizes",
"items": {
"type": "string"
},
"type": "array"
},
"tags": {
"items": {
"type": "string"
},
"type": "array"
},
"transport_layer": {
"enum": [
"tcp",
"udp",
"tcp_udp"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"version": {
"type": "integer"
},
"visibility": {
"enum": [
"visible",
"hidden",
"disabled"
],
"type": "string"
}
},
"required": [
"id",
"inbound_id",
"server_id",
"server_name",
"protocol",
"transport_layer",
"name",
"name_i18n",
"kind",
"connect_host",
"connect_port",
"port",
"address_family",
"region_code",
"tags",
"system_tags",
"client_overrides",
"visibility",
"sort",
"created_at",
"updated_at",
"version"
],
"type": "object"
},
"NetworkNodeInput": {
"additionalProperties": false,
"properties": {
"address_family": {
"default": "ipv4",
"enum": [
"ipv4",
"ipv6",
"dual"
],
"type": "string"
},
"client_overrides": {
"additionalProperties": false,
"default": {},
"properties": {
"allow_insecure": {
"type": "boolean"
},
"alpn": {
"items": {
"enum": [
"h3",
"h2",
"http/1.1"
],
"type": "string"
},
"maxItems": 3,
"minItems": 1,
"type": "array"
},
"fingerprint": {
"enum": [
"chrome",
"firefox",
"safari",
"ios",
"android",
"edge",
"random",
"randomized"
],
"type": "string"
},
"host": {
"maxLength": 253,
"type": "string"
},
"path": {
"maxLength": 256,
"pattern": "^\\/[\\x21-\\x7e]*$",
"type": "string"
},
"server_name": {
"maxLength": 253,
"type": "string"
},
"service_name": {
"maxLength": 128,
"minLength": 1,
"pattern": "^[A-Za-z0-9_./-]+$",
"type": "string"
}
},
"type": "object"
},
"connect_host": {
"maxLength": 253,
"type": "string"
},
"connect_port": {
"default": null,
"maximum": 65535,
"minimum": 1,
"type": [
"integer",
"null"
]
},
"inbound_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"default": "direct",
"enum": [
"direct",
"relay",
"cdn"
],
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"name_i18n": {
"additionalProperties": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"default": {},
"type": "object"
},
"region_code": {
"default": null,
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"type": [
"string",
"null"
]
},
"sort": {
"default": 0,
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"tags": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 64,
"type": "array"
},
"visibility": {
"default": "visible",
"enum": [
"visible",
"hidden",
"disabled"
],
"type": "string"
}
},
"required": [
"inbound_id",
"name",
"connect_host"
],
"type": "object"
},
"NetworkNodeList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/NetworkNode"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"NetworkNodePage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/NetworkNode"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NetworkNodeReorderInput": {
"additionalProperties": false,
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"sort": {
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
}
},
"required": [
"id",
"sort"
],
"type": "object"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"NetworkNodeReorderResult": {
"properties": {
"updated": {
"type": "integer"
}
},
"required": [
"updated"
],
"type": "object"
},
"NetworkNodeTagsInput": {
"additionalProperties": false,
"properties": {
"add": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 64,
"type": "array"
},
"node_ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
},
"remove": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 64,
"type": "array"
}
},
"required": [
"node_ids"
],
"type": "object"
},
"NetworkNodeTagsResult": {
"properties": {
"updated": {
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
},
"required": [
"updated"
],
"type": "object"
},
"NetworkProtocolList": {
"properties": {
"items": {
"items": {
"properties": {
"params_schema": {
"description": "JSON Schema of `params` (input form)"
},
"protocol": {
"type": "string"
},
"secret_paths": {
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
},
"transport_layers": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"protocol",
"title",
"transport_layers",
"secret_paths"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"NetworkRepublish": {
"properties": {
"changed": {
"type": "boolean"
},
"hash": {
"type": "string"
},
"revision": {
"type": "integer"
},
"server_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"server_id",
"changed",
"revision",
"hash"
],
"type": "object"
},
"NetworkRuntimeDefaults": {
"properties": {
"runtime": {
"additionalProperties": {},
"description": "ip_strategy, dns, outbounds, routing_rules, block_rules",
"type": "object"
},
"version": {
"description": "network settings version (0 = code defaults)",
"type": "integer"
}
},
"required": [
"runtime",
"version"
],
"type": "object"
},
"NetworkRuntimeDefaultsInput": {
"additionalProperties": false,
"properties": {
"runtime": {
"additionalProperties": false,
"properties": {
"block_rules": {
"items": {
"additionalProperties": false,
"properties": {
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"ips": {
"default": [],
"items": {
"anyOf": [
{
"format": "ipv4-cidr",
"type": "string"
},
{
"format": "ipv6-cidr",
"type": "string"
},
{
"format": "ip",
"type": "string"
},
{
"format": "ip",
"type": "string"
}
]
},
"maxItems": 1000,
"type": "array"
},
"protocols": {
"default": [],
"items": {
"enum": [
"http",
"tls",
"quic",
"bittorrent"
],
"type": "string"
},
"maxItems": 4,
"type": "array"
}
},
"type": "object"
},
"maxItems": 64,
"type": "array"
},
"dns": {
"items": {
"additionalProperties": false,
"properties": {
"address": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"required": [
"address"
],
"type": "object"
},
"maxItems": 32,
"type": "array"
},
"ip_strategy": {
"enum": [
"as_is",
"prefer_ipv4",
"prefer_ipv6",
"ipv4_only",
"ipv6_only"
],
"type": "string"
},
"outbounds": {
"items": {
"additionalProperties": false,
"properties": {
"protocol": {
"enum": [
"direct",
"socks",
"http",
"shadowsocks",
"vless",
"vmess",
"trojan",
"wireguard"
],
"type": "string"
},
"settings": {
"additionalProperties": {},
"default": {},
"type": "object"
},
"tag": {
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}$",
"type": "string"
}
},
"required": [
"tag",
"protocol"
],
"type": "object"
},
"maxItems": 64,
"type": "array"
},
"routing_rules": {
"items": {
"additionalProperties": false,
"properties": {
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"ips": {
"default": [],
"items": {
"anyOf": [
{
"format": "ipv4-cidr",
"type": "string"
},
{
"format": "ipv6-cidr",
"type": "string"
},
{
"format": "ip",
"type": "string"
},
{
"format": "ip",
"type": "string"
}
]
},
"maxItems": 1000,
"type": "array"
},
"network": {
"enum": [
"tcp",
"udp",
"tcp,udp"
],
"type": "string"
},
"outbound": {
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}$",
"type": "string"
},
"ports": {
"pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$",
"type": "string"
},
"protocols": {
"default": [],
"items": {
"enum": [
"http",
"tls",
"quic",
"bittorrent"
],
"type": "string"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"outbound"
],
"type": "object"
},
"maxItems": 256,
"type": "array"
}
},
"required": [
"ip_strategy",
"dns",
"outbounds",
"routing_rules",
"block_rules"
],
"type": "object"
}
},
"required": [
"runtime"
],
"type": "object"
},
"NetworkRuntimeOverridesInput": {
"additionalProperties": false,
"properties": {
"overrides": {
"additionalProperties": false,
"properties": {
"block_rules": {
"items": {
"additionalProperties": false,
"properties": {
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"ips": {
"default": [],
"items": {
"anyOf": [
{
"format": "ipv4-cidr",
"type": "string"
},
{
"format": "ipv6-cidr",
"type": "string"
},
{
"format": "ip",
"type": "string"
},
{
"format": "ip",
"type": "string"
}
]
},
"maxItems": 1000,
"type": "array"
},
"protocols": {
"default": [],
"items": {
"enum": [
"http",
"tls",
"quic",
"bittorrent"
],
"type": "string"
},
"maxItems": 4,
"type": "array"
}
},
"type": "object"
},
"maxItems": 64,
"type": "array"
},
"dns": {
"items": {
"additionalProperties": false,
"properties": {
"address": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
}
},
"required": [
"address"
],
"type": "object"
},
"maxItems": 32,
"type": "array"
},
"ip_strategy": {
"enum": [
"as_is",
"prefer_ipv4",
"prefer_ipv6",
"ipv4_only",
"ipv6_only"
],
"type": "string"
},
"outbounds": {
"items": {
"additionalProperties": false,
"properties": {
"protocol": {
"enum": [
"direct",
"socks",
"http",
"shadowsocks",
"vless",
"vmess",
"trojan",
"wireguard"
],
"type": "string"
},
"settings": {
"additionalProperties": {},
"default": {},
"type": "object"
},
"tag": {
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}$",
"type": "string"
}
},
"required": [
"tag",
"protocol"
],
"type": "object"
},
"maxItems": 64,
"type": "array"
},
"routing_rules": {
"items": {
"additionalProperties": false,
"properties": {
"domains": {
"default": [],
"items": {
"maxLength": 253,
"minLength": 1,
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"ips": {
"default": [],
"items": {
"anyOf": [
{
"format": "ipv4-cidr",
"type": "string"
},
{
"format": "ipv6-cidr",
"type": "string"
},
{
"format": "ip",
"type": "string"
},
{
"format": "ip",
"type": "string"
}
]
},
"maxItems": 1000,
"type": "array"
},
"network": {
"enum": [
"tcp",
"udp",
"tcp,udp"
],
"type": "string"
},
"outbound": {
"pattern": "^[a-z0-9][a-z0-9_-]{0,31}$",
"type": "string"
},
"ports": {
"pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$",
"type": "string"
},
"protocols": {
"default": [],
"items": {
"enum": [
"http",
"tls",
"quic",
"bittorrent"
],
"type": "string"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"outbound"
],
"type": "object"
},
"maxItems": 256,
"type": "array"
}
},
"type": "object"
}
},
"required": [
"overrides"
],
"type": "object"
},
"NetworkServer": {
"properties": {
"access_checked_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"access_version": {
"type": "integer"
},
"address": {
"type": "string"
},
"agent": {
"properties": {
"enrollment_expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"last_error": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"previous_token_valid_until": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"program": {
"additionalProperties": {},
"type": [
"object",
"null"
]
},
"status": {
"enum": [
"pending",
"active",
"disabled"
],
"type": "string"
},
"token_prefix": {
"type": [
"string",
"null"
]
}
},
"required": [
"status",
"token_prefix",
"previous_token_valid_until",
"enrollment_expires_at",
"program",
"last_seen_at",
"last_error"
],
"type": "object"
},
"applied": {
"properties": {
"at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"hash": {
"type": [
"string",
"null"
]
},
"revision": {
"type": [
"integer",
"null"
]
}
},
"required": [
"revision",
"hash",
"at"
],
"type": "object"
},
"country_code": {
"type": [
"string",
"null"
]
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"desired": {
"properties": {
"hash": {
"type": [
"string",
"null"
]
},
"rendered_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer"
}
},
"required": [
"revision",
"hash",
"rendered_at"
],
"type": "object"
},
"health": {
"enum": [
"unknown",
"healthy",
"degraded",
"offline",
"config_drift",
"auth_failed",
"protocol_conflict"
],
"type": "string"
},
"health_changed_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"inbound_count": {
"type": "integer"
},
"ip_geo_status": {
"enum": [
"ok",
"unresolved",
"manual"
],
"type": "string"
},
"last_status": {
"additionalProperties": {},
"description": "Latest heartbeat sample (load, speed, connectivity)",
"type": [
"object",
"null"
]
},
"last_status_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"node_count": {
"type": "integer"
},
"region_code": {
"type": [
"string",
"null"
]
},
"reported_ipv4": {
"type": [
"string",
"null"
]
},
"reported_ipv6": {
"type": [
"string",
"null"
]
},
"runtime_overrides": {
"additionalProperties": {},
"description": "Override patch over the network runtime defaults",
"type": "object"
},
"sort": {
"type": "integer"
},
"status": {
"enum": [
"active",
"maintenance",
"retired"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"name",
"region_code",
"country_code",
"ip_geo_status",
"address",
"status",
"sort",
"runtime_overrides",
"agent",
"health",
"health_changed_at",
"last_status",
"last_status_at",
"reported_ipv4",
"reported_ipv6",
"desired",
"applied",
"access_version",
"access_checked_at",
"inbound_count",
"node_count",
"created_at",
"updated_at",
"version"
],
"type": "object"
},
"NetworkServerConfig": {
"properties": {
"applied": {
"properties": {
"at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"hash": {
"type": [
"string",
"null"
]
},
"revision": {
"type": [
"integer",
"null"
]
}
},
"required": [
"revision",
"hash",
"at"
],
"type": "object"
},
"defaults": {
"additionalProperties": {},
"type": "object"
},
"desired": {
"properties": {
"config": {
"additionalProperties": {},
"description": "Secrets appear as { \"$secret\": true }",
"type": [
"object",
"null"
]
},
"hash": {
"type": [
"string",
"null"
]
},
"rendered_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"revision": {
"type": "integer"
}
},
"required": [
"revision",
"hash",
"rendered_at",
"config"
],
"type": "object"
},
"effective": {
"additionalProperties": {},
"description": "defaults ⊕ overrides: what the next render sends",
"type": "object"
},
"overrides": {
"additionalProperties": {},
"type": "object"
},
"server_id": {
"format": "uuid",
"type": "string"
},
"settings_version": {
"type": "integer"
},
"version": {
"description": "Server version (If-Match of PUT …/runtime)",
"type": "integer"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"server_id",
"version",
"defaults",
"settings_version",
"overrides",
"effective",
"desired",
"applied",
"warnings"
],
"type": "object"
},
"NetworkServerHealth": {
"properties": {
"agent_status": {
"enum": [
"pending",
"active",
"disabled"
],
"type": "string"
},
"applied_revision": {
"type": [
"integer",
"null"
]
},
"current": {
"properties": {
"health": {
"enum": [
"unknown",
"healthy",
"degraded",
"offline",
"config_drift",
"auth_failed",
"protocol_conflict"
],
"type": "string"
},
"reasons": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"health",
"reasons"
],
"type": "object"
},
"desired_revision": {
"type": "integer"
},
"health": {
"enum": [
"unknown",
"healthy",
"degraded",
"offline",
"config_drift",
"auth_failed",
"protocol_conflict"
],
"type": "string"
},
"health_changed_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"inbound_results": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"last_error": {
"type": [
"string",
"null"
]
},
"last_seen_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"last_status": {
"additionalProperties": {},
"type": [
"object",
"null"
]
},
"last_usage_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"server_id": {
"format": "uuid",
"type": "string"
},
"usage_silent": {
"type": "boolean"
}
},
"required": [
"server_id",
"health",
"health_changed_at",
"current",
"agent_status",
"last_seen_at",
"desired_revision",
"applied_revision",
"inbound_results",
"last_status",
"usage_silent",
"last_usage_at",
"last_error"
],
"type": "object"
},
"NetworkServerInput": {
"additionalProperties": false,
"properties": {
"address": {
"maxLength": 253,
"type": "string"
},
"country_code": {
"default": null,
"pattern": "^[A-Z]{2}$",
"type": [
"string",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"region_code": {
"default": null,
"pattern": "^[a-z][a-z0-9-]{0,31}$",
"type": [
"string",
"null"
]
},
"sort": {
"default": 0,
"maximum": 1000000,
"minimum": -1000000,
"type": "integer"
},
"status": {
"default": "active",
"enum": [
"active",
"maintenance"
],
"type": "string"
}
},
"required": [
"name",
"address"
],
"type": "object"
},
"NetworkServerPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/NetworkServer"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NetworkServerStats": {
"properties": {
"current": {
"properties": {
"at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"rx_bps": {
"type": [
"string",
"null"
]
},
"tx_bps": {
"type": [
"string",
"null"
]
}
},
"required": [
"rx_bps",
"tx_bps",
"at"
],
"type": "object"
},
"date_from": {
"type": "string"
},
"date_to": {
"type": "string"
},
"days": {
"items": {
"properties": {
"avg_bps": {
"description": "(rx + tx) ÷ covered seconds",
"type": [
"string",
"null"
]
},
"conns_max": {
"type": "integer"
},
"covered_seconds": {
"type": "integer"
},
"cpu_avg": {
"type": [
"number",
"null"
]
},
"cpu_max": {
"type": "number"
},
"date": {
"type": "string"
},
"max_bps": {
"description": "Larger per-direction 1-second peak",
"type": "string"
},
"mem_max": {
"type": "number"
},
"online_users_max": {
"type": "integer"
},
"rx_bytes": {
"type": "string"
},
"samples": {
"type": "integer"
},
"tx_bytes": {
"type": "string"
}
},
"required": [
"date",
"samples",
"covered_seconds",
"rx_bytes",
"tx_bytes",
"avg_bps",
"max_bps",
"cpu_avg",
"cpu_max",
"mem_max",
"conns_max",
"online_users_max"
],
"type": "object"
},
"type": "array"
},
"max_daily_bytes_30d": {
"type": "string"
},
"max_daily_date": {
"type": [
"string",
"null"
]
},
"server_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"server_id",
"date_from",
"date_to",
"days",
"max_daily_bytes_30d",
"max_daily_date",
"current"
],
"type": "object"
},
"NetworkTagChange": {
"properties": {
"nodes": {
"type": "integer"
},
"plans": {
"type": "integer"
},
"servers": {
"description": "Servers queued for an access recompute",
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"sources": {
"items": {
"type": "string"
},
"type": "array"
},
"subscriptions": {
"type": "integer"
},
"target": {
"type": "string"
}
},
"required": [
"target",
"sources",
"nodes",
"plans",
"subscriptions",
"servers"
],
"type": "object"
},
"NetworkTagImpact": {
"properties": {
"items": {
"items": {
"properties": {
"active_subscriptions": {
"type": "integer"
},
"nodes": {
"type": "integer"
},
"plans": {
"type": "integer"
},
"subscriptions": {
"type": "integer"
},
"tag": {
"type": "string"
}
},
"required": [
"tag",
"nodes",
"plans",
"subscriptions",
"active_subscriptions"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"NetworkTagList": {
"properties": {
"items": {
"items": {
"properties": {
"active_subscription_count": {
"type": "integer"
},
"display": {
"description": "Display names and colour from the network settings domain",
"properties": {
"color": {
"type": [
"string",
"null"
]
},
"names": {
"additionalProperties": {
"type": "string"
},
"type": "object"
}
},
"required": [
"names",
"color"
],
"type": [
"object",
"null"
]
},
"health": {
"description": "Nodes by their server's health",
"properties": {
"auth_failed": {
"type": "integer"
},
"config_drift": {
"type": "integer"
},
"degraded": {
"type": "integer"
},
"healthy": {
"type": "integer"
},
"offline": {
"type": "integer"
},
"protocol_conflict": {
"type": "integer"
},
"unknown": {
"type": "integer"
}
},
"type": "object"
},
"node_count": {
"type": "integer"
},
"plan_count": {
"type": "integer"
},
"system": {
"description": "Derived tag: filters and groups only, never authorizes",
"type": "boolean"
},
"tag": {
"type": "string"
}
},
"required": [
"tag",
"system",
"node_count",
"plan_count",
"active_subscription_count",
"health",
"display"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"NetworkTagMergeInput": {
"additionalProperties": false,
"properties": {
"into": {
"maxLength": 128,
"type": "string"
},
"sources": {
"items": {
"maxLength": 128,
"type": "string"
},
"maxItems": 64,
"minItems": 1,
"type": "array"
}
},
"required": [
"sources",
"into"
],
"type": "object"
},
"NetworkTagRenameInput": {
"additionalProperties": false,
"properties": {
"from": {
"maxLength": 128,
"type": "string"
},
"to": {
"maxLength": 128,
"type": "string"
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"NotificationPreferences": {
"additionalProperties": false,
"properties": {
"billing": {
"additionalProperties": false,
"properties": {
"email": {
"type": "boolean"
},
"inbox": {
"type": "boolean"
},
"sms": {
"type": "boolean"
},
"telegram": {
"type": "boolean"
}
},
"type": "object"
},
"marketing": {
"additionalProperties": false,
"properties": {
"email": {
"type": "boolean"
},
"inbox": {
"type": "boolean"
},
"sms": {
"type": "boolean"
},
"telegram": {
"type": "boolean"
}
},
"type": "object"
},
"ops": {
"additionalProperties": false,
"properties": {
"email": {
"type": "boolean"
},
"inbox": {
"type": "boolean"
},
"sms": {
"type": "boolean"
},
"telegram": {
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
},
"NotifyDelivery": {
"properties": {
"attempts": {
"type": "integer"
},
"category": {
"enum": [
"security",
"billing",
"service",
"marketing",
"ops"
],
"type": "string"
},
"channel": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"event_key": {
"type": "string"
},
"id": {
"type": "string"
},
"last_error": {
"description": "Masked provider errors, one per tried provider",
"type": [
"string",
"null"
]
},
"next_attempt_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"provider_message_id": {
"type": [
"string",
"null"
]
},
"recipient_id": {
"type": [
"string",
"null"
]
},
"recipient_type": {
"enum": [
"user",
"staff",
"address"
],
"type": "string"
},
"sent_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"sending",
"sent",
"failed",
"suppressed",
"dead"
],
"type": "string"
},
"target": {
"description": "Masked target, e.g. a***@example.com",
"type": "string"
},
"template_key": {
"type": "string"
}
},
"required": [
"id",
"event_key",
"template_key",
"category",
"channel",
"recipient_type",
"recipient_id",
"target",
"status",
"attempts",
"next_attempt_at",
"provider",
"provider_message_id",
"last_error",
"created_at",
"sent_at"
],
"type": "object"
},
"NotifyDeliveryDetail": {
"properties": {
"attempts": {
"type": "integer"
},
"category": {
"enum": [
"security",
"billing",
"service",
"marketing",
"ops"
],
"type": "string"
},
"channel": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"event_key": {
"type": "string"
},
"id": {
"type": "string"
},
"last_error": {
"description": "Masked provider errors, one per tried provider",
"type": [
"string",
"null"
]
},
"locale": {
"type": [
"string",
"null"
]
},
"next_attempt_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"provider_message_id": {
"type": [
"string",
"null"
]
},
"recipient_id": {
"type": [
"string",
"null"
]
},
"recipient_type": {
"enum": [
"user",
"staff",
"address"
],
"type": "string"
},
"retryable": {
"description": "POST …/retry is possible",
"type": "boolean"
},
"sent_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"sending",
"sent",
"failed",
"suppressed",
"dead"
],
"type": "string"
},
"target": {
"description": "Masked target, e.g. a***@example.com",
"type": "string"
},
"template_key": {
"type": "string"
},
"time_zone": {
"type": [
"string",
"null"
]
},
"values": {
"additionalProperties": {},
"description": "Template values; sensitive ones as ***",
"type": "object"
}
},
"required": [
"id",
"event_key",
"template_key",
"category",
"channel",
"recipient_type",
"recipient_id",
"target",
"status",
"attempts",
"next_attempt_at",
"provider",
"provider_message_id",
"last_error",
"created_at",
"sent_at",
"locale",
"time_zone",
"values",
"retryable"
],
"type": "object"
},
"NotifyDeliveryPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/NotifyDelivery"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NotifyTemplate": {
"properties": {
"body": {
"type": "string"
},
"builtin": {
"description": "Built-in text of this locale, if any",
"properties": {
"body": {
"type": "string"
},
"subject": {
"type": [
"string",
"null"
]
}
},
"required": [
"subject",
"body"
],
"type": [
"object",
"null"
]
},
"category": {
"enum": [
"security",
"billing",
"service",
"marketing",
"ops"
],
"type": "string"
},
"channel": {
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"customized": {
"description": "A stored row overrides the built-in text",
"type": "boolean"
},
"description": {
"type": "string"
},
"key": {
"type": "string"
},
"locale": {
"type": "string"
},
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"subject": {
"type": [
"string",
"null"
]
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"updated_by": {
"type": [
"string",
"null"
]
},
"variables": {
"items": {
"properties": {
"kind": {
"enum": [
"text",
"url",
"number",
"datetime",
"date",
"bytes",
"money"
],
"type": "string"
},
"name": {
"type": "string"
},
"sample": {
"$ref": "#/components/schemas/NotifyVariableValue"
},
"sensitive": {
"description": "Masked in delivery records, erased after sending",
"type": "boolean"
}
},
"required": [
"name",
"kind",
"sensitive",
"sample"
],
"type": "object"
},
"type": "array"
},
"version": {
"description": "0 = the built-in text, never saved (If-Match \"v0\" creates)",
"type": "integer"
}
},
"required": [
"key",
"channel",
"locale",
"category",
"description",
"subject",
"body",
"origin",
"version",
"customized",
"builtin",
"variables",
"updated_by",
"updated_at"
],
"type": "object"
},
"NotifyTemplateList": {
"properties": {
"has_more": {
"enum": [
false
],
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/NotifyTemplate"
},
"type": "array"
},
"next_cursor": {
"type": "null"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"NotifyTemplateUpdate": {
"additionalProperties": false,
"properties": {
"body": {
"maxLength": 100000,
"type": "string"
},
"subject": {
"maxLength": 255,
"type": [
"string",
"null"
]
}
},
"required": [
"subject",
"body"
],
"type": "object"
},
"NotifyTestSend": {
"additionalProperties": false,
"properties": {
"channel": {
"default": "email",
"enum": [
"email",
"sms",
"telegram",
"inbox"
],
"type": "string"
},
"draft": {
"additionalProperties": false,
"description": "Unsaved text to render instead of the stored one",
"properties": {
"body": {
"maxLength": 100000,
"type": "string"
},
"subject": {
"maxLength": 255,
"type": [
"string",
"null"
]
}
},
"required": [
"subject",
"body"
],
"type": [
"object",
"null"
]
},
"dry_run": {
"description": "Render only (preview)",
"type": "boolean"
},
"key": {
"maxLength": 100,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$",
"type": "string"
},
"locale": {
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"provider_id": {
"description": "Send through this provider only (provider test; also requires notify.provider.manage)",
"maxLength": 32,
"type": [
"string",
"null"
]
},
"to": {
"description": "Required unless dry_run; own verified email unless the actor holds notify.provider.manage",
"format": "email",
"maxLength": 254,
"type": [
"string",
"null"
]
},
"values": {
"additionalProperties": {
"$ref": "#/components/schemas/NotifyVariableValue"
},
"description": "Overrides of the samples",
"type": "object"
}
},
"required": [
"key",
"locale"
],
"type": "object"
},
"NotifyTestSendResult": {
"properties": {
"attempts": {
"items": {
"properties": {
"error": {
"type": "string"
},
"message_id": {
"type": "string"
},
"outcome": {
"enum": [
"sent",
"failed",
"skipped"
],
"type": "string"
},
"provider_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"type": {
"type": "string"
}
},
"required": [
"provider_id",
"type",
"outcome"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale of the text used, after fallback",
"type": "string"
},
"message_id": {
"type": [
"string",
"null"
]
},
"provider_id": {
"type": [
"string",
"null"
]
},
"rendered": {
"properties": {
"html": {
"type": "string"
},
"subject": {
"type": "string"
},
"text": {
"type": "string"
}
},
"required": [
"subject",
"text",
"html"
],
"type": "object"
},
"sent": {
"description": "null for a dry run",
"type": [
"boolean",
"null"
]
},
"target": {
"type": [
"string",
"null"
]
}
},
"required": [
"rendered",
"locale",
"sent",
"target",
"provider_id",
"message_id",
"attempts"
],
"type": "object"
},
"NotifyVariableValue": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"properties": {
"currency": {
"type": "string"
},
"minor": {
"type": "string"
}
},
"required": [
"minor",
"currency"
],
"type": "object"
}
]
},
"OpsAlertRoute": {
"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"
},
"id": {
"format": "uuid",
"type": "string"
},
"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"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"enabled",
"exception_types",
"severities",
"staff_ids",
"channels",
"throttle_seconds",
"id",
"version"
],
"type": "object"
},
"OpsException": {
"properties": {
"events": {
"description": "First occurrence and append-only handling history",
"items": {
"description": "JSON value"
},
"type": "array"
},
"fingerprint": {
"type": "string"
},
"first_seen_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"last_seen_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"occurrences": {
"type": "integer"
},
"owner_staff_id": {
"type": [
"string",
"null"
]
},
"resource_refs": {
"items": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"type": "array"
},
"severity": {
"enum": [
"p1",
"p2",
"p3"
],
"type": "string"
},
"source": {
"type": "string"
},
"status": {
"enum": [
"open",
"acknowledged",
"muted",
"resolved"
],
"type": "string"
},
"type": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"fingerprint",
"source",
"type",
"severity",
"status",
"owner_staff_id",
"resource_refs",
"first_seen_at",
"last_seen_at",
"occurrences",
"events",
"version"
],
"type": "object"
},
"OpsExceptionPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/OpsException"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"OpsExport": {
"properties": {
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"filters": {
"additionalProperties": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"orders",
"payments",
"users",
"usage"
],
"type": "string"
},
"operator_id": {
"format": "uuid",
"type": "string"
},
"reason": {
"type": "string"
},
"row_count": {
"type": [
"integer",
"null"
]
},
"row_limit": {
"type": "integer"
},
"status": {
"enum": [
"pending",
"ready",
"failed",
"expired"
],
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"id",
"kind",
"operator_id",
"reason",
"row_limit",
"filters",
"status",
"row_count",
"truncated",
"created_at",
"expires_at"
],
"type": "object"
},
"PermissionCatalogue": {
"properties": {
"capabilities": {
"items": {
"properties": {
"code": {
"type": "string"
},
"phase": {
"type": "string"
}
},
"required": [
"code",
"phase"
],
"type": "object"
},
"type": "array"
},
"permissions": {
"items": {
"properties": {
"code": {
"type": "string"
},
"module": {
"type": "string"
},
"phase": {
"type": "string"
},
"sensitive": {
"type": "boolean"
}
},
"required": [
"code",
"module",
"phase",
"sensitive"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"permissions",
"capabilities"
],
"type": "object"
},
"PortalFileUploadCreate": {
"allOf": [
{
"$ref": "#/components/schemas/FileUploadCreate"
},
{
"properties": {
"purpose": {
"enum": [
"ticket_attachment"
],
"type": "string"
}
},
"type": "object"
}
]
},
"Problem": {
"description": "RFC 9457 problem details. Clients branch on `code`, never on `title` or `detail`.",
"properties": {
"code": {
"description": "Stable `<module>.<reason>` code, see `x-error-codes`",
"type": "string"
},
"current": {
"additionalProperties": {},
"description": "Current resource summary, only on 409 concurrency conflicts",
"type": "object"
},
"detail": {
"type": "string"
},
"details": {
"additionalProperties": {},
"type": "object"
},
"errors": {
"description": "Per-field validation errors (422)",
"items": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"path",
"code"
],
"type": "object"
},
"type": "array"
},
"request_id": {
"type": "string"
},
"status": {
"type": "integer"
},
"title": {
"type": "string"
},
"type": {
"description": "`urn:error:<code>`",
"type": "string"
}
},
"required": [
"type",
"title",
"status",
"code",
"request_id"
],
"type": "object"
},
"PublicCatalog": {
"properties": {
"locale": {
"description": "Locale of the texts (also `Content-Language`)",
"type": "string"
},
"products": {
"items": {
"$ref": "#/components/schemas/PublicCatalogProduct"
},
"type": "array"
}
},
"required": [
"locale",
"products"
],
"type": "object"
},
"PublicCatalogPlan": {
"properties": {
"code": {
"type": "string"
},
"description_md": {
"type": [
"string",
"null"
]
},
"device_limit": {
"type": [
"integer",
"null"
]
},
"features": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"per_user_limit": {
"type": [
"integer",
"null"
]
},
"prices": {
"items": {
"$ref": "#/components/schemas/PublicCatalogPrice"
},
"type": "array"
},
"reset_on_renewal": {
"type": "boolean"
},
"reset_policy": {
"enum": [
"none",
"billing_cycle",
"calendar_month",
"calendar_year"
],
"type": "string"
},
"sold_out": {
"type": "boolean"
},
"speed_limit_mbps": {
"type": [
"integer",
"null"
]
},
"subtitle": {
"type": [
"string",
"null"
]
},
"traffic_quota_bytes": {
"description": "Bytes per period; null = unlimited",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"code",
"name",
"subtitle",
"description_md",
"features",
"traffic_quota_bytes",
"speed_limit_mbps",
"device_limit",
"reset_policy",
"reset_on_renewal",
"per_user_limit",
"sold_out",
"prices"
],
"type": "object"
},
"PublicCatalogPrice": {
"properties": {
"amount": {
"$ref": "#/components/schemas/CatalogMoney"
},
"compare_at": {
"allOf": [
{
"$ref": "#/components/schemas/CatalogMoney"
},
{
"type": [
"object",
"null"
]
}
]
},
"id": {
"format": "uuid",
"type": "string"
},
"period_count": {
"type": "integer"
},
"period_unit": {
"enum": [
"day",
"month",
"year",
"none"
],
"type": "string"
}
},
"required": [
"id",
"period_unit",
"period_count",
"amount",
"compare_at"
],
"type": "object"
},
"PublicCatalogProduct": {
"properties": {
"description_md": {
"type": [
"string",
"null"
]
},
"features": {
"items": {
"type": "string"
},
"type": "array"
},
"group_key": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"plans": {
"items": {
"$ref": "#/components/schemas/PublicCatalogPlan"
},
"type": "array"
},
"slug": {
"type": "string"
},
"subtitle": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"slug",
"group_key",
"name",
"subtitle",
"description_md",
"features",
"plans"
],
"type": "object"
},
"PublicInvitation": {
"properties": {
"expires_at": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"inviter": {
"description": "Masked display name or email of the inviter",
"type": "string"
},
"kind": {
"enum": [
"customer",
"staff"
],
"type": "string"
},
"status": {
"enum": [
"pending",
"accepted",
"rejected",
"canceled",
"expired"
],
"type": "string"
}
},
"required": [
"id",
"inviter",
"kind",
"status",
"expires_at"
],
"type": "object"
},
"Readiness": {
"properties": {
"app_schema": {
"type": "integer"
},
"app_schema_required": {
"type": "integer"
},
"checks": {
"additionalProperties": {
"additionalProperties": {},
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"type": "object"
},
"type": "object"
},
"db_min_app_schema": {
"type": [
"integer",
"null"
]
},
"db_version": {
"type": [
"integer",
"null"
]
},
"installed": {
"type": [
"boolean",
"null"
]
},
"reason": {
"description": "database_unavailable, not_migrated, database_too_old, code_too_old, not_installed or a check name",
"type": "string"
},
"status": {
"enum": [
"ready",
"not_ready"
],
"type": "string"
}
},
"required": [
"status",
"app_schema",
"app_schema_required",
"db_version",
"db_min_app_schema",
"installed"
],
"type": "object"
},
"ReauthRequest": {
"oneOf": [
{
"properties": {
"method": {
"enum": [
"password"
],
"type": "string"
},
"password": {
"maxLength": 128,
"minLength": 1,
"type": "string"
}
},
"required": [
"method",
"password"
],
"type": "object"
},
{
"properties": {
"code": {
"pattern": "^\\d{6}$",
"type": "string"
},
"method": {
"enum": [
"totp"
],
"type": "string"
}
},
"required": [
"method",
"code"
],
"type": "object"
}
]
},
"ReauthResult": {
"properties": {
"mfa_verified_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"reauth_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"reauth_at",
"mfa_verified_at"
],
"type": "object"
},
"RepairCatalogue": {
"properties": {
"items": {
"items": {
"properties": {
"allowed": {
"description": "Whether the caller holds the command permission",
"type": "boolean"
},
"command": {
"type": "string"
},
"description": {
"type": "string"
},
"input_schema": {
"description": "JSON Schema of `input`"
},
"permission": {
"type": "string"
},
"target_type": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"command",
"title",
"description",
"permission",
"target_type",
"allowed"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"RepairCommand": {
"properties": {
"command": {
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"executed_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"expected_version": {
"description": "Target fingerprint captured by the preview; send it back to execute",
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"input": {
"description": "JSON value"
},
"operator_id": {
"type": "string"
},
"preview_expires_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"reason": {
"type": "string"
},
"request_id": {
"type": [
"string",
"null"
]
},
"result": {
"description": "JSON value"
},
"status": {
"enum": [
"previewed",
"executing",
"succeeded",
"partial",
"failed",
"expired"
],
"type": "string"
},
"summary": {
"description": "What execution will do"
},
"target": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
}
},
"required": [
"id",
"command",
"target",
"status",
"expected_version",
"reason",
"operator_id",
"request_id",
"preview_expires_at",
"created_at",
"executed_at"
],
"type": "object"
},
"RepairCommandPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/RepairCommand"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"Role": {
"properties": {
"assignable": {
"description": "Whether the caller’s codes include all of this role’s",
"type": "boolean"
},
"kind": {
"enum": [
"static",
"protected",
"preset",
"custom"
],
"type": "string"
},
"permissions": {
"items": {
"type": "string"
},
"type": "array"
},
"role": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"role",
"kind",
"permissions",
"assignable",
"updated_at"
],
"type": "object"
},
"RoleCreate": {
"additionalProperties": false,
"properties": {
"permissions": {
"items": {
"maxLength": 64,
"type": "string"
},
"maxItems": 200,
"type": "array"
},
"role": {
"pattern": "^[a-z][a-z0-9_]{1,31}$",
"type": "string"
}
},
"required": [
"role",
"permissions"
],
"type": "object"
},
"RoleList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/Role"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"RoleUpdate": {
"additionalProperties": false,
"properties": {
"permissions": {
"items": {
"maxLength": 64,
"type": "string"
},
"maxItems": 200,
"type": "array"
}
},
"required": [
"permissions"
],
"type": "object"
},
"SessionsRevoked": {
"properties": {
"sessions_revoked": {
"type": "integer"
}
},
"required": [
"sessions_revoked"
],
"type": "object"
},
"SettingsDocument": {
"properties": {
"domain": {
"type": "string"
},
"updated_at": {
"type": [
"string",
"null"
]
},
"value": {
"additionalProperties": {},
"description": "Full document; secrets as { \"set\": boolean }",
"type": "object"
},
"version": {
"description": "0 until the domain is first saved (code defaults)",
"type": "integer"
}
},
"required": [
"domain",
"value",
"version",
"updated_at"
],
"type": "object"
},
"SettingsDomainList": {
"properties": {
"items": {
"items": {
"properties": {
"domain": {
"type": "string"
},
"owner": {
"type": "string"
},
"reauth": {
"type": "boolean"
},
"writable": {
"type": "boolean"
}
},
"required": [
"domain",
"owner",
"writable",
"reauth"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"SettingsRevision": {
"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"
},
"value": {
"additionalProperties": {},
"type": "object"
},
"version": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
}
},
"required": [
"domain",
"revision",
"version",
"base_version",
"status",
"note",
"created_at",
"published_at",
"value"
],
"type": "object"
},
"SettingsRevisionDiff": {
"properties": {
"fields": {
"items": {
"properties": {
"after": {},
"before": {},
"changed": {
"type": "boolean"
},
"path": {
"type": "string"
},
"secret": {
"type": "boolean"
}
},
"required": [
"path",
"secret",
"changed"
],
"type": "object"
},
"type": "array"
},
"published_version": {
"maximum": 2147483647,
"minimum": 0,
"type": "integer"
}
},
"required": [
"published_version",
"fields"
],
"type": "object"
},
"SettingsUpdate": {
"additionalProperties": false,
"properties": {
"value": {
"additionalProperties": {},
"description": "Full document; omitted secrets and { \"set\": … } markers keep the stored secret",
"type": "object"
}
},
"required": [
"value"
],
"type": "object"
},
"SiteInfo": {
"properties": {
"appearance": {
"properties": {
"brand_color": {
"type": [
"string",
"null"
]
},
"hero_glass": {
"type": "boolean"
},
"theme_preset": {
"type": "string"
}
},
"required": [
"theme_preset",
"brand_color",
"hero_glass"
],
"type": "object"
},
"captcha": {
"properties": {
"scenes": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"turnstile_site_key": {
"type": [
"string",
"null"
]
}
},
"required": [
"scenes",
"turnstile_site_key"
],
"type": "object"
},
"currency": {
"type": "string"
},
"description": {
"type": "string"
},
"landing": {
"properties": {
"cta_body": {
"type": "string"
},
"cta_text": {
"type": "string"
},
"cta_title": {
"type": "string"
},
"features": {
"items": {
"properties": {
"description": {
"type": "string"
},
"image": {
"properties": {
"alt": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url",
"alt"
],
"type": [
"object",
"null"
]
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"type": "array"
},
"hero_body": {
"type": "string"
},
"hero_media": {
"oneOf": [
{
"properties": {
"alt": {
"type": "string"
},
"kind": {
"enum": [
"image"
],
"type": "string"
},
"poster_url": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url",
"alt",
"kind"
],
"type": "object"
},
{
"properties": {
"alt": {
"type": "string"
},
"kind": {
"enum": [
"video"
],
"type": "string"
},
"poster_url": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url",
"alt",
"kind",
"poster_url"
],
"type": "object"
},
{
"type": "null"
}
]
},
"hero_title": {
"type": "string"
},
"steps": {
"items": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"hero_title",
"hero_body",
"features",
"steps",
"cta_title",
"cta_body",
"cta_text"
],
"type": [
"object",
"null"
]
},
"locale": {
"type": "string"
},
"locales": {
"properties": {
"available": {
"items": {
"type": "string"
},
"type": "array"
},
"source": {
"type": "string"
}
},
"required": [
"source",
"available"
],
"type": "object"
},
"logo_url": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"registration": {
"properties": {
"mode": {
"enum": [
"open",
"invite_only",
"closed"
],
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
},
"seo": {
"properties": {
"announcements": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"download": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"features": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"home": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"pricing": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
},
"status": {
"properties": {
"description": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"title",
"description"
],
"type": "object"
}
},
"type": "object"
},
"social_image_url": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": "string"
}
},
"required": [
"name",
"locale",
"locales",
"description",
"logo_url",
"social_image_url",
"landing",
"seo",
"currency",
"timezone",
"appearance",
"registration",
"captcha"
],
"type": "object"
},
"Staff": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"public_id": {
"type": "string"
},
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"status": {
"type": "string"
},
"two_factor_enabled": {
"type": "boolean"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"public_id",
"email",
"name",
"roles",
"status",
"two_factor_enabled",
"created_at"
],
"type": "object"
},
"StaffDetail": {
"allOf": [
{
"$ref": "#/components/schemas/Staff"
},
{
"properties": {
"assignable_roles": {
"description": "Roles the caller may grant or remove",
"items": {
"type": "string"
},
"type": "array"
},
"permissions": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"permissions",
"assignable_roles"
],
"type": "object"
}
]
},
"StaffList": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/Staff"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"StaffMfaReset": {
"properties": {
"sessions_revoked": {
"type": "integer"
}
},
"required": [
"sessions_revoked"
],
"type": "object"
},
"StaffRoles": {
"properties": {
"roles": {
"items": {
"type": "string"
},
"type": "array"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"roles"
],
"type": "object"
},
"StaffRolesUpdate": {
"additionalProperties": false,
"properties": {
"roles": {
"items": {
"maxLength": 32,
"type": "string"
},
"maxItems": 32,
"type": "array"
}
},
"required": [
"roles"
],
"type": "object"
},
"SubscriptionEvent": {
"properties": {
"actor": {
"properties": {
"id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"detail": {
"additionalProperties": {},
"type": "object"
},
"id": {
"type": "string"
},
"kind": {
"type": "string"
}
},
"required": [
"id",
"kind",
"actor",
"detail",
"created_at"
],
"type": "object"
},
"SubscriptionEventPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/SubscriptionEvent"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"SubscriptionGrant": {
"properties": {
"actor": {
"properties": {
"id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"applied_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"effect": {
"enum": [
"activate_plan",
"term_extend",
"traffic_bonus",
"device_bonus",
"usage_reset",
"plan_switch"
],
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"params": {
"additionalProperties": {},
"type": "object"
},
"reason": {
"type": [
"string",
"null"
]
},
"reverses_grant_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"source": {
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"order",
"code",
"admin",
"bulk",
"referral",
"trial",
"apple",
"plan_change",
"refund"
],
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"status": {
"enum": [
"pending",
"applied",
"reversed"
],
"type": "string"
},
"term_end_after": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"term_end_before": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"effect",
"source",
"idempotency_key",
"params",
"status",
"applied_at",
"term_end_before",
"term_end_after",
"reverses_grant_id",
"actor",
"reason",
"created_at"
],
"type": "object"
},
"SubscriptionGrantPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/SubscriptionGrant"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"SubscriptionLink": {
"properties": {
"rotated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"token_fingerprint": {
"type": "string"
},
"url": {
"description": "Subscription URL `https://<subscription host>/s/<token>`",
"type": "string"
}
},
"required": [
"url",
"token_fingerprint",
"rotated_at"
],
"type": "object"
},
"SubscriptionTerm": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 3650,
"minimum": 1,
"type": "integer"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"unit",
"count"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "`{ \"perpetual\": true }` or `{ \"unit\": \"month\", \"count\": 1 }`"
},
"TranslateRequest": {
"additionalProperties": false,
"properties": {
"id": {
"example": "0192f0c4-0000-7000-8000-00000000abcd",
"maxLength": 80,
"minLength": 1,
"pattern": "^[A-Za-z0-9_./:-]+$",
"type": "string"
},
"locales": {
"description": "Target locales; default every enabled locale except the source",
"items": {
"example": "en-US",
"maxLength": 35,
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"maxItems": 32,
"minItems": 1,
"type": "array"
},
"overwrite": {
"description": "Retranslate filled locales too (confirmed by the staff member)",
"type": "boolean"
},
"type": {
"example": "catalog.product",
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$",
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"TranslateResult": {
"properties": {
"id": {
"type": "string"
},
"requested": {
"items": {
"properties": {
"fields": {
"items": {
"type": "string"
},
"type": "array"
},
"job_id": {
"description": "null when a pending job already covers it",
"type": [
"string",
"null"
]
},
"locale": {
"type": "string"
}
},
"required": [
"locale",
"fields",
"job_id"
],
"type": "object"
},
"type": "array"
},
"skipped": {
"enum": [
"auto_translate_off",
"no_provider",
null
],
"type": [
"string",
"null"
]
},
"source_locale": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id",
"source_locale",
"requested",
"skipped"
],
"type": "object"
},
"TranslationAttempt": {
"properties": {
"characters": {
"type": "integer"
},
"outcome": {
"enum": [
"ok",
"disabled",
"not_configured",
"unsupported_locale",
"text_too_long",
"over_budget",
"quota_exceeded",
"rate_limited",
"auth_failed",
"timeout",
"failed",
"invalid_response",
"placeholder_mismatch"
],
"type": "string"
},
"provider_id": {
"type": "string"
},
"status": {
"description": "HTTP status or provider error code",
"type": "string"
},
"type": {
"enum": [
"aliyun",
"volcengine",
"youdao",
"niutrans",
"caiyun",
"yandex",
"workers_ai",
"microsoft",
"google",
"deepl_free",
"deepl",
"baidu",
"tencent",
"libretranslate",
"openai_compatible"
],
"type": "string"
}
},
"required": [
"provider_id",
"type",
"outcome"
],
"type": "object"
},
"TranslationJob": {
"properties": {
"attempts": {
"type": "integer"
},
"attempts_log": {
"items": {
"$ref": "#/components/schemas/TranslationAttempt"
},
"type": "array"
},
"id": {
"type": "string"
},
"last_error": {
"type": [
"string",
"null"
]
},
"max_attempts": {
"type": "integer"
},
"outcome": {
"description": "translated, no_provider, needs_manual, retry, gone, source_locale, locale_disabled, nothing_missing, target_changed",
"type": [
"string",
"null"
]
},
"overwrite": {
"type": "boolean"
},
"provider": {
"type": [
"string",
"null"
]
},
"run_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"status": {
"enum": [
"pending",
"running",
"succeeded",
"dead",
"cancelled"
],
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"status",
"overwrite",
"attempts",
"max_attempts",
"run_at",
"updated_at",
"last_error",
"outcome",
"provider",
"attempts_log"
],
"type": [
"object",
"null"
]
},
"TranslationLocaleStatus": {
"properties": {
"enabled": {
"type": "boolean"
},
"job": {
"$ref": "#/components/schemas/TranslationJob"
},
"locale": {
"type": "string"
},
"missing_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"origin": {
"enum": [
"manual",
"machine",
"builtin",
null
],
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"state": {
"enum": [
"source",
"complete",
"missing",
"translating",
"failed",
"needs_manual"
],
"type": "string"
}
},
"required": [
"locale",
"enabled",
"state",
"origin",
"provider",
"missing_fields",
"job"
],
"type": "object"
},
"TranslationOverview": {
"properties": {
"auto_translate": {
"type": "boolean"
},
"default_locale": {
"type": "string"
},
"enabled_locales": {
"items": {
"type": "string"
},
"type": "array"
},
"jobs": {
"properties": {
"dead": {
"type": "integer"
},
"pending": {
"type": "integer"
},
"running": {
"type": "integer"
}
},
"required": [
"pending",
"running",
"dead"
],
"type": "object"
},
"kind": {
"enum": [
"overview"
],
"type": "string"
},
"period": {
"description": "Calendar month (UTC) of the character counts",
"example": "2026-10",
"type": "string"
},
"providers": {
"items": {
"properties": {
"configured": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"monthly_char_budget": {
"description": "Characters per month",
"type": [
"integer",
"null"
]
},
"type": {
"enum": [
"aliyun",
"volcengine",
"youdao",
"niutrans",
"caiyun",
"yandex",
"workers_ai",
"microsoft",
"google",
"deepl_free",
"deepl",
"baidu",
"tencent",
"libretranslate",
"openai_compatible"
],
"type": "string"
},
"used_this_month": {
"description": "Counted characters (best effort)",
"type": [
"integer",
"null"
]
}
},
"required": [
"id",
"type",
"label",
"enabled",
"configured",
"monthly_char_budget",
"used_this_month"
],
"type": "object"
},
"type": "array"
},
"resource_types": {
"items": {
"properties": {
"fields": {
"items": {
"type": "string"
},
"type": "array"
},
"owner": {
"type": "string"
},
"permission": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type",
"owner",
"fields",
"permission"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"kind",
"default_locale",
"enabled_locales",
"auto_translate",
"period",
"providers",
"jobs",
"resource_types"
],
"type": "object"
},
"TranslationProviderTest": {
"additionalProperties": false,
"properties": {
"source_locale": {
"description": "Default: the site default locale",
"example": "en-US",
"maxLength": 35,
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"target_locale": {
"description": "Default: the first other enabled locale",
"example": "en-US",
"maxLength": 35,
"pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\\d{3}))?$",
"type": "string"
},
"text": {
"description": "Default: a built-in zh / en sample",
"maxLength": 2000,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"TranslationProviderTestResult": {
"properties": {
"characters": {
"type": "integer"
},
"elapsed_ms": {
"type": "integer"
},
"provider_id": {
"type": "string"
},
"source_locale": {
"type": "string"
},
"target_locale": {
"type": "string"
},
"text": {
"type": "string"
},
"translated": {
"type": "string"
},
"type": {
"enum": [
"aliyun",
"volcengine",
"youdao",
"niutrans",
"caiyun",
"yandex",
"workers_ai",
"microsoft",
"google",
"deepl_free",
"deepl",
"baidu",
"tencent",
"libretranslate",
"openai_compatible"
],
"type": "string"
}
},
"required": [
"provider_id",
"type",
"source_locale",
"target_locale",
"text",
"translated",
"characters",
"elapsed_ms"
],
"type": "object"
},
"TranslationResourceStatus": {
"properties": {
"fields": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"kind": {
"enum": [
"resource"
],
"type": "string"
},
"locales": {
"items": {
"$ref": "#/components/schemas/TranslationLocaleStatus"
},
"type": "array"
},
"source_locale": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"kind",
"type",
"id",
"source_locale",
"fields",
"locales"
],
"type": "object"
},
"TranslationStatus": {
"discriminator": {
"mapping": {
"overview": "#/components/schemas/TranslationOverview",
"resource": "#/components/schemas/TranslationResourceStatus"
},
"propertyName": "kind"
},
"oneOf": [
{
"$ref": "#/components/schemas/TranslationOverview"
},
{
"$ref": "#/components/schemas/TranslationResourceStatus"
}
]
},
"UsageDaily": {
"properties": {
"items": {
"items": {
"properties": {
"billed_bytes": {
"pattern": "^\\d+$",
"type": "string"
},
"business_date": {
"format": "date",
"type": "string"
},
"download_bytes": {
"pattern": "^\\d+$",
"type": "string"
},
"upload_bytes": {
"pattern": "^\\d+$",
"type": "string"
}
},
"required": [
"business_date",
"upload_bytes",
"download_bytes",
"billed_bytes"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"UsageDevices": {
"properties": {
"items": {
"items": {
"properties": {
"blocked_until": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"device_key": {
"type": "string"
},
"first_seen_at": {
"format": "date-time",
"type": "string"
},
"ip_masked": {
"type": "string"
},
"last_seen_at": {
"format": "date-time",
"type": "string"
},
"limited": {
"type": "boolean"
},
"reason": {
"type": [
"string",
"null"
]
},
"server_id": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"device_key",
"ip_masked",
"server_id",
"first_seen_at",
"last_seen_at",
"limited",
"reason",
"blocked_until"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
},
"UsageKickedDevice": {
"properties": {
"blocked_until": {
"format": "date-time",
"type": "string"
}
},
"required": [
"blocked_until"
],
"type": "object"
},
"UsageRankings": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"billed_bytes": {
"pattern": "^\\d+$",
"type": "string"
},
"download_bytes": {
"pattern": "^\\d+$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"upload_bytes": {
"pattern": "^\\d+$",
"type": "string"
}
},
"required": [
"id",
"upload_bytes",
"download_bytes",
"billed_bytes"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"has_more",
"next_cursor"
],
"type": "object"
},
"UsageReconciliationReport": {
"properties": {
"batch_date_from": {
"format": "date",
"type": "string"
},
"batch_date_to": {
"format": "date",
"type": "string"
},
"compared_server_days": {
"type": "integer"
},
"compared_subscriptions": {
"type": "integer"
},
"differences": {
"items": {
"properties": {
"actual_billed_bytes": {
"type": [
"string",
"null"
]
},
"actual_raw_bytes": {
"type": [
"string",
"null"
]
},
"business_date": {
"format": "date",
"type": [
"string",
"null"
]
},
"detail": {
"additionalProperties": {},
"type": "object"
},
"exception_id": {
"format": "uuid",
"type": "string"
},
"expected_billed_bytes": {
"type": [
"string",
"null"
]
},
"expected_raw_bytes": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"batch_daily",
"subscription_counter",
"incomplete_period"
],
"type": "string"
},
"resource_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"resource_id",
"business_date",
"expected_raw_bytes",
"actual_raw_bytes",
"expected_billed_bytes",
"actual_billed_bytes",
"detail",
"exception_id"
],
"type": "object"
},
"type": "array"
},
"incomplete": {
"items": {
"properties": {
"actual_billed_bytes": {
"type": [
"string",
"null"
]
},
"actual_raw_bytes": {
"type": [
"string",
"null"
]
},
"business_date": {
"format": "date",
"type": [
"string",
"null"
]
},
"detail": {
"additionalProperties": {},
"type": "object"
},
"expected_billed_bytes": {
"type": [
"string",
"null"
]
},
"expected_raw_bytes": {
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"batch_daily",
"subscription_counter",
"incomplete_period"
],
"type": "string"
},
"resource_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"resource_id",
"business_date",
"expected_raw_bytes",
"actual_raw_bytes",
"expected_billed_bytes",
"actual_billed_bytes",
"detail"
],
"type": "object"
},
"type": "array"
},
"incomplete_subscriptions": {
"type": "integer"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"timezone": {
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"timezone",
"batch_date_from",
"batch_date_to",
"compared_server_days",
"compared_subscriptions",
"incomplete_subscriptions",
"differences",
"incomplete",
"truncated",
"next_cursor"
],
"type": "object"
},
"UserCoupon": {
"properties": {
"bulk_operation_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"coupon": {
"properties": {
"code": {
"type": [
"string",
"null"
]
},
"distribution": {
"enum": [
"public",
"issued"
],
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name",
"distribution",
"code"
],
"type": "object"
},
"created_at": {
"type": "string"
},
"discount": {
"$ref": "#/components/schemas/CouponDiscount"
},
"id": {
"format": "uuid",
"type": "string"
},
"order_id": {
"description": "Reserving / first consuming order",
"format": "uuid",
"type": [
"string",
"null"
]
},
"recurring": {
"$ref": "#/components/schemas/UserCouponRecurring"
},
"reserved_order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"scope": {
"$ref": "#/components/schemas/CouponScope"
},
"source": {
"enum": [
"checkout",
"admin",
"bulk",
"registration",
"referral"
],
"type": "string"
},
"status": {
"enum": [
"available",
"reserved",
"consumed",
"released",
"reversed",
"expired",
"revoked"
],
"type": "string"
},
"subscription_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"updated_at": {
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
},
"valid_from": {
"type": [
"string",
"null"
]
},
"valid_until": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"status",
"source",
"discount",
"scope",
"recurring",
"valid_from",
"valid_until",
"reserved_order_id",
"subscription_id",
"created_at",
"user_id",
"coupon",
"order_id",
"bulk_operation_id",
"updated_at",
"version"
],
"type": "object"
},
"UserCouponPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/UserCoupon"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
},
"UserCouponRecurring": {
"properties": {
"mode": {
"enum": [
"once",
"periods",
"forever"
],
"type": "string"
},
"periods": {
"type": [
"integer",
"null"
]
},
"periods_remaining": {
"description": "null = unlimited",
"type": [
"integer",
"null"
]
},
"periods_used": {
"type": "integer"
}
},
"required": [
"mode",
"periods",
"periods_used",
"periods_remaining"
],
"type": "object"
},
"UserCouponRevoke": {
"additionalProperties": false,
"properties": {
"reason": {
"description": "Recorded in the audit event",
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
},
"UserStatus": {
"properties": {
"sessions_revoked": {
"type": "integer"
},
"status": {
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"status",
"sessions_revoked"
],
"type": "object"
},
"UserStatusChange": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"status": {
"enum": [
"active",
"disabled",
"banned"
],
"type": "string"
}
},
"required": [
"status",
"reason"
],
"type": "object"
},
"Wallet": {
"properties": {
"balances": {
"properties": {
"cash": {
"$ref": "#/components/schemas/LedgerMoney"
},
"commission": {
"$ref": "#/components/schemas/LedgerMoney"
},
"commission_pending": {
"$ref": "#/components/schemas/LedgerMoney"
},
"gift": {
"$ref": "#/components/schemas/LedgerMoney"
}
},
"required": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "object"
},
"currency": {
"example": "USD",
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"updated_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": [
"string",
"null"
]
},
"user_id": {
"format": "uuid",
"type": "string"
},
"version": {
"type": "integer"
},
"withdrawal_blocked": {
"description": "Available commission is negative",
"type": "boolean"
}
},
"required": [
"user_id",
"currency",
"balances",
"withdrawal_blocked",
"version",
"updated_at"
],
"type": "object"
},
"WalletAdjustment": {
"properties": {
"amount": {
"$ref": "#/components/schemas/LedgerMoney"
},
"approval_required": {
"type": "boolean"
},
"bucket": {
"enum": [
"cash",
"gift"
],
"type": "string"
},
"entry": {
"$ref": "#/components/schemas/AdminWalletEntry"
},
"id": {
"format": "uuid",
"type": "string"
},
"reason": {
"type": "string"
},
"request": {
"allOf": [
{
"$ref": "#/components/schemas/WalletAdjustmentReview"
},
{
"type": [
"object",
"null"
]
}
]
},
"status": {
"enum": [
"posted",
"pending",
"approved",
"rejected",
"withdrawn",
"expired"
],
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
},
"wallet": {
"$ref": "#/components/schemas/Wallet"
}
},
"required": [
"id",
"user_id",
"bucket",
"amount",
"reason",
"approval_required",
"status",
"request",
"entry",
"wallet"
],
"type": "object"
},
"WalletAdjustmentRequest": {
"additionalProperties": false,
"properties": {
"amount": {
"additionalProperties": false,
"properties": {
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"minor": {
"description": "Signed, non-zero: positive credits, negative debits",
"example": "-500",
"pattern": "^-?[1-9]\\d{0,17}$",
"type": "string"
}
},
"required": [
"currency",
"minor"
],
"type": "object"
},
"bucket": {
"enum": [
"cash",
"gift"
],
"type": "string"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"bucket",
"amount",
"reason"
],
"type": "object"
},
"WalletAdjustmentReview": {
"properties": {
"amount": {
"$ref": "#/components/schemas/LedgerMoney"
},
"bucket": {
"enum": [
"cash",
"gift"
],
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"decided_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"decided_by": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"decision_reason": {
"type": [
"string",
"null"
]
},
"entry_id": {
"type": [
"string",
"null"
]
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"reason": {
"type": "string"
},
"requested_by": {
"format": "uuid",
"type": "string"
},
"status": {
"enum": [
"pending",
"approved",
"rejected",
"withdrawn",
"expired"
],
"type": "string"
},
"user_id": {
"format": "uuid",
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"id",
"user_id",
"requested_by",
"bucket",
"amount",
"reason",
"status",
"expires_at",
"created_at",
"version",
"decided_by",
"decided_at",
"decision_reason",
"entry_id"
],
"type": "object"
},
"WalletEntry": {
"properties": {
"amount": {
"$ref": "#/components/schemas/LedgerMoney"
},
"balance_after": {
"$ref": "#/components/schemas/LedgerMoney"
},
"bucket": {
"enum": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "string"
},
"created_at": {
"example": "2026-10-22T08:00:00.000Z",
"format": "date-time",
"type": "string"
},
"id": {
"example": "1042",
"type": "string"
},
"kind": {
"enum": [
"top_up",
"order_apply",
"order_release",
"order_reapply",
"order_payment",
"refund",
"admin_adjust",
"gift_grant",
"commission_accrue",
"commission_release",
"commission_reverse",
"commission_to_cash",
"withdraw_hold",
"withdraw_release",
"commission_withdraw_hold",
"commission_withdraw_release",
"commission_withdraw_settle",
"correction"
],
"type": "string"
},
"reference": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
}
},
"required": [
"id",
"bucket",
"kind",
"amount",
"balance_after",
"reference",
"created_at"
],
"type": "object"
},
"WalletEntryPage": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/WalletEntry"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"total": {
"type": "integer"
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
}