{
  "openapi": "3.1.0",
  "info": {
    "title": "QiuGe Helper Cloud API",
    "summary": "Publicly documented subset of the QiuGe Helper cloud control-plane API.",
    "description": "This specification documents the stable public subset that the marketing site advertises for automated discovery. The platform uses bearer-token authentication and does not currently publish OAuth or OIDC discovery metadata.",
    "version": "0.3.10"
  },
  "servers": [
    {
      "url": "https://qiugeapi.zhangqiu.pro",
      "description": "Production Cloudflare Worker"
    }
  ],
  "tags": [
    {
      "name": "health",
      "description": "Public health checks"
    },
    {
      "name": "auth",
      "description": "Platform account registration and login"
    },
    {
      "name": "profile",
      "description": "Authenticated account profile"
    },
    {
      "name": "subscription",
      "description": "Plan discovery"
    },
    {
      "name": "quota",
      "description": "Authenticated usage quota endpoints"
    },
    {
      "name": "ai",
      "description": "Authenticated AI lease and usage reporting endpoints"
    }
  ],
  "paths": {
    "/api/cloud/health": {
      "get": {
        "tags": ["health"],
        "operationId": "getCloudHealth",
        "summary": "Get cloud API health",
        "responses": {
          "200": {
            "description": "Worker health status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/auth/register-code/request": {
      "post": {
        "tags": ["auth"],
        "operationId": "requestRegisterCode",
        "summary": "Request registration verification code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification token created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationTokenResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/auth/register": {
      "post": {
        "tags": ["auth"],
        "operationId": "registerCloudAccount",
        "summary": "Register a platform account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/auth/login": {
      "post": {
        "tags": ["auth"],
        "operationId": "loginCloudAccount",
        "summary": "Log in to a platform account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/auth/refresh": {
      "post": {
        "tags": ["auth"],
        "operationId": "refreshCloudSession",
        "summary": "Refresh the current cloud session",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Refreshed authenticated session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/me": {
      "get": {
        "tags": ["profile"],
        "operationId": "getCurrentAccount",
        "summary": "Get the authenticated account snapshot",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account, membership, entitlement, and subscription snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["profile"],
        "operationId": "updateCurrentAccount",
        "summary": "Update the authenticated account profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated account profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/subscription/plans": {
      "get": {
        "tags": ["subscription"],
        "operationId": "listSubscriptionPlans",
        "summary": "List purchaseable subscription plans",
        "responses": {
          "200": {
            "description": "Available plans",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlansResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/quota": {
      "get": {
        "tags": ["quota"],
        "operationId": "getQuotaSnapshot",
        "summary": "Get the authenticated account quota snapshot",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Quota snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotaResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/ai/credential-leases": {
      "post": {
        "tags": ["ai"],
        "operationId": "createCredentialLease",
        "summary": "Request a short-lived AI credential lease",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CredentialLeaseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lease granted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialLeaseResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cloud/ai/usage-reports": {
      "post": {
        "tags": ["ai"],
        "operationId": "createUsageReport",
        "summary": "Report AI usage after a completed task",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UsageReportRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Usage report accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "QiuGe Helper cloud bearer token returned by login or refresh endpoints."
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["ok"],
        "additionalProperties": true
      },
      "RegisterCodeRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          }
        },
        "required": ["email"],
        "additionalProperties": false
      },
      "VerificationTokenResponse": {
        "type": "object",
        "properties": {
          "verificationToken": {
            "type": "string"
          }
        },
        "required": ["verificationToken"],
        "additionalProperties": true
      },
      "RegisterRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "password": {
            "type": "string",
            "minLength": 8
          },
          "displayName": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "verificationToken": {
            "type": "string"
          }
        },
        "required": ["email", "password", "code", "verificationToken"],
        "additionalProperties": false
      },
      "LoginRequest": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "password": {
            "type": "string"
          }
        },
        "required": ["email", "password"],
        "additionalProperties": false
      },
      "AuthSessionResponse": {
        "type": "object",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/Account"
          },
          "token": {
            "type": "string"
          }
        },
        "required": ["account", "token"],
        "additionalProperties": true
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "displayName": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "tierKey": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": ["id", "email"],
        "additionalProperties": true
      },
      "Entitlement": {
        "type": "object",
        "properties": {
          "tierKey": {
            "type": "string"
          },
          "tierName": {
            "type": "string"
          },
          "effectiveModuleKeys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "allowedRouteKeys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "WorkspaceSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": ["id", "name"],
        "additionalProperties": true
      },
      "SubscriptionSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "planKey": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/Account"
          },
          "entitlement": {
            "$ref": "#/components/schemas/Entitlement"
          },
          "workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkspaceSummary"
            }
          },
          "subscription": {
            "$ref": "#/components/schemas/SubscriptionSummary"
          }
        },
        "required": ["account"],
        "additionalProperties": true
      },
      "UpdateMeRequest": {
        "type": "object",
        "properties": {
          "displayName": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "wechat": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SubscriptionPlan": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "billingPeriod": {
            "type": "string"
          },
          "priceCents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          }
        },
        "required": ["key", "name"],
        "additionalProperties": true
      },
      "SubscriptionPlansResponse": {
        "type": "object",
        "properties": {
          "plans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubscriptionPlan"
            }
          }
        },
        "required": ["plans"],
        "additionalProperties": true
      },
      "QuotaBucket": {
        "type": "object",
        "properties": {
          "quotaKey": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "used": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "resetAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["quotaKey", "limit", "used", "remaining"],
        "additionalProperties": true
      },
      "QuotaResponse": {
        "type": "object",
        "properties": {
          "buckets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuotaBucket"
            }
          }
        },
        "required": ["buckets"],
        "additionalProperties": true
      },
      "CredentialLeaseRequest": {
        "type": "object",
        "properties": {
          "capability": {
            "type": "string",
            "enum": ["chat", "translation", "image"]
          },
          "providerId": {
            "type": "string"
          },
          "model": {
            "type": "string"
          }
        },
        "required": ["capability"],
        "additionalProperties": false
      },
      "CredentialLeaseResponse": {
        "type": "object",
        "properties": {
          "leaseId": {
            "type": "string"
          },
          "providerId": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "allowedModels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "quotaHint": {
            "type": "object"
          }
        },
        "required": ["leaseId", "providerId", "expiresAt"],
        "additionalProperties": true
      },
      "UsageReportRequest": {
        "type": "object",
        "properties": {
          "leaseId": {
            "type": "string"
          },
          "workspaceId": {
            "type": "string"
          },
          "membershipId": {
            "type": "string"
          },
          "providerId": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "capability": {
            "type": "string"
          },
          "inputTokens": {
            "type": "integer",
            "minimum": 0
          },
          "outputTokens": {
            "type": "integer",
            "minimum": 0
          },
          "status": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          }
        },
        "required": ["capability", "status"],
        "additionalProperties": true
      },
      "OkResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": ["ok"],
        "additionalProperties": true
      }
    }
  }
}