PPanel Edgesubscriptions
由 openapi.json 自动生成的 21 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/subscriptions
GET /api/v1/admin/subscriptions
Search subscriptions, newest first (keyset pages)
{
"parameters": [
{
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"scheduled",
"active",
"exhausted",
"expired",
"cancelled",
"refunded"
],
"type": "string"
},
{
"items": {
"enum": [
"scheduled",
"active",
"exhausted",
"expired",
"cancelled",
"refunded"
],
"type": "string"
},
"type": "array"
}
],
"description": "Status; repeat the parameter for several values"
}
},
{
"description": "Source; repeat the parameter for several values",
"in": "query",
"name": "source",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"order",
"code",
"admin",
"trial",
"apple"
],
"type": "string"
},
{
"items": {
"enum": [
"order",
"code",
"admin",
"trial",
"apple"
],
"type": "string"
},
"type": "array"
}
],
"description": "Source; repeat the parameter for several values"
}
},
{
"in": "query",
"name": "plan_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Subscription id, public id (S…), node short id or node UUID",
"in": "query",
"name": "q",
"required": false,
"schema": {
"description": "Subscription id, public id (S…), node short id or node UUID",
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "term_end_from",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "term_end_to",
"required": false,
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionPage"
}
}
},
"description": "A page of subscriptions"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "Search subscriptions, newest first (keyset pages)",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "subscription.subscription.read",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions
POST /api/v1/admin/subscriptions
Open a subscription for a user (queued behind a running one unless activation is immediate)
{
"parameters": [
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The new subscription",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Unknown user, plan or price option; a retired plan; validation failed"
}
},
"summary": "Open a subscription for a user (queued behind a running one unless activation is immediate)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.create",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true
},
"x-idempotency": "required",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/admin/subscriptions/{id}
GET /api/v1/admin/subscriptions/{id}
One subscription with its available actions (ETag: version)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "One subscription with its available actions (ETag: version)",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "subscription.subscription.read",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/activate
POST /api/v1/admin/subscriptions/{id}/activate
Start a queued subscription now (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Start a queued subscription now (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.activate",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/auto-renew/disable
POST /api/v1/admin/subscriptions/{id}/auto-renew/disable
Switch balance auto-renew off (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Switch balance auto-renew off (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.auto_renew.disable",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/cancel
POST /api/v1/admin/subscriptions/{id}/cancel
Cancel (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionReason"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Cancel (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.cancel",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/admin/subscriptions/{id}/events
GET /api/v1/admin/subscriptions/{id}/events
Lifecycle events of a subscription, newest first
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionEventPage"
}
}
},
"description": "A page of events"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "Lifecycle events of a subscription, newest first",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "subscription.subscription.read",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/extend
POST /api/v1/admin/subscriptions/{id}/extend
Extend by a term or set the end (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionExtend"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Extend by a term or set the end (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.extend",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/grant-traffic
POST /api/v1/admin/subscriptions/{id}/grant-traffic
Grant bonus traffic for the current period (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionGrantTraffic"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Grant bonus traffic for the current period (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.grant_traffic",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/admin/subscriptions/{id}/grants
GET /api/v1/admin/subscriptions/{id}/grants
Entitlement grants of a subscription, newest first
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionGrantPage"
}
}
},
"description": "A page of grants"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "Entitlement grants of a subscription, newest first",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "subscription.subscription.read",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/reset-usage
POST /api/v1/admin/subscriptions/{id}/reset-usage
Reset the usage period (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionReason"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Reset the usage period (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.reset_usage",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/resume
POST /api/v1/admin/subscriptions/{id}/resume
Resume (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Resume (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.resume",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/rotate-credential
POST /api/v1/admin/subscriptions/{id}/rotate-credential
Rotate the node credential (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Rotate the node credential (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.credential.rotate",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/set-limits
POST /api/v1/admin/subscriptions/{id}/set-limits
Adjust device, speed and traffic limits (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionLimits"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Adjust device, speed and traffic limits (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.set_limits",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}POST /api/v1/admin/subscriptions/{id}/suspend
POST /api/v1/admin/subscriptions/{id}/suspend
Suspend (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscriptionReason"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminSubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Validation failed"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Suspend (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.suspend",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "subscription.subscription.manage",
"effectiveSecurity": []
}GET /api/v1/me/subscriptions
GET /api/v1/me/subscriptions
My subscriptions, newest first (keyset pages)
{
"parameters": [
{
"description": "Status; repeat the parameter for several values",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"scheduled",
"active",
"exhausted",
"expired",
"cancelled",
"refunded"
],
"type": "string"
},
{
"items": {
"enum": [
"scheduled",
"active",
"exhausted",
"expired",
"cancelled",
"refunded"
],
"type": "string"
},
"type": "array"
}
],
"description": "Status; repeat the parameter for several values"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MySubscriptionPage"
}
}
},
"description": "A page of my subscriptions"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "My subscriptions, newest first (keyset pages)",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}GET /api/v1/me/subscriptions/{id}
GET /api/v1/me/subscriptions/{id}
One of my subscriptions (ETag: version)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/MySubscription"
},
{
"properties": {
"team_eligible": {
"type": "boolean"
}
},
"required": [
"team_eligible"
],
"type": "object"
}
]
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "One of my subscriptions (ETag: version)",
"tags": [
"subscriptions"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}POST /api/v1/me/subscriptions/{id}/activate
POST /api/v1/me/subscriptions/{id}/activate
Start a queued subscription now, beside the current one (If-Match)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MySubscription"
}
}
},
"description": "The started subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Start a queued subscription now, beside the current one (If-Match)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.activate",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "optional",
"effectiveSecurity": []
}PUT /api/v1/me/subscriptions/{id}/auto-renew
PUT /api/v1/me/subscriptions/{id}/auto-renew
Set balance auto-renew and its price option
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"price_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"enabled"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/MySubscription"
},
{
"properties": {
"auto_renew_estimate": {
"properties": {
"amount_minor": {
"type": "string"
},
"balance_minor": {
"type": "string"
},
"next_charge_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"sufficient": {
"type": "boolean"
}
},
"required": [
"amount_minor",
"balance_minor",
"sufficient",
"next_charge_at"
],
"type": [
"object",
"null"
]
}
},
"required": [
"auto_renew_estimate"
],
"type": "object"
}
]
}
}
},
"description": "Subscription and renewal estimate"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "common.version_conflict (with current) or a subscription.* conflict"
},
"412": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Malformed If-Match"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match missing"
}
},
"summary": "Set balance auto-renew and its price option",
"tags": [
"subscriptions"
],
"x-audit": "subscription.auto_renew.update",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"effectiveSecurity": []
}GET /api/v1/me/subscriptions/{id}/link
GET /api/v1/me/subscriptions/{id}/link
The subscription link (issued on first view)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubscriptionLink"
}
}
},
"description": "The link"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "The subscription link (issued on first view)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.link.read",
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}POST /api/v1/me/subscriptions/{id}/rotate-credential
POST /api/v1/me/subscriptions/{id}/rotate-credential
Replace the node credential (clients must re-import the subscription)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MySubscription"
}
}
},
"description": "The subscription"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such subscription"
}
},
"summary": "Replace the node credential (clients must re-import the subscription)",
"tags": [
"subscriptions"
],
"x-audit": "subscription.credential.rotate",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "required",
"effectiveSecurity": []
}