{
  "openapi": "3.1.0",
  "info": {
    "title": "QuickFind Open API",
    "version": "1.0.0",
    "summary": "QuickFind 开放平台接口",
    "description": "QuickFind 开放 API 提供对账号侧云端数据与插件生态的 HTTP 访问。\n\n**四个家族，四种鉴权**：\n- `/api/v1/*` — Bearer API 密钥（qf_live_ 前缀），按端点校验作用域；\n- `/api/developer/*` — 用户会话 JWT，面向插件开发者本人；\n- `/api/shared-index/*` — 用户会话 JWT + 团队归属门；\n- `/api/signing-keys/*` — 公开，用于插件包验签。\n\n**列表分页**：orders / invoices / submissions 使用 cursor-page/1 契约（默认 50 条、上限 200 条）。\n**幂等**：所有 POST 建议带 `Idempotency-Key`，重复请求不会重复执行。\n\n本文件由 `_tools/build_api_openapi.js` 从源码常量生成，端点与作用域与线上代码同源。",
    "contact": {
      "name": "QuickFind 开放平台",
      "url": "https://api.quickfindapp.com/"
    },
    "license": {
      "name": "QuickFind 开放平台使用条款",
      "url": "https://www.quickfindapp.com/terms.html"
    }
  },
  "servers": [
    {
      "url": "https://api.quickfindapp.com",
      "description": "生产（开放平台独立主机）"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "v1",
      "description": "账号侧接口：Bearer API 密钥鉴权，按 read:<资源> 授权。"
    },
    {
      "name": "developer",
      "description": "开发者侧接口：用户会话 JWT，需通过开发者状态门。"
    },
    {
      "name": "shared-index",
      "description": "团队共享索引：用户会话 JWT + 团队归属门（测试版）。"
    },
    {
      "name": "signing-keys",
      "description": "插件签名公钥与验签：公开，无需鉴权。"
    },
    {
      "name": "system",
      "description": "活性探测。"
    }
  ],
  "paths": {
    "/api/v1/me": {
      "get": {
        "summary": "当前密钥身份与配额",
        "description": "无需作用域。无需任何作用域，适合作为拿到密钥后的第一个调用。",
        "operationId": "v1_api_v1_me",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "key": {
                      "type": "object",
                      "properties": {
                        "prefix": {
                          "type": "string",
                          "example": "qf_live_"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "quota": {
                      "type": "object",
                      "properties": {
                        "per_minute": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "used": {
                              "type": "integer"
                            }
                          }
                        },
                        "per_day": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "used": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "近 7 天用量与限流统计",
        "description": "需要作用域：read:usage。按天、按端点、按状态码三个维度聚合，含被限流（429）次数。",
        "operationId": "v1_api_v1_usage",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/favorites": {
      "get": {
        "summary": "收藏列表",
        "description": "需要作用域：read:favorites。",
        "operationId": "v1_api_v1_favorites",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "favorites": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "搜索历史",
        "description": "需要作用域：read:history。",
        "operationId": "v1_api_v1_history",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/devices": {
      "get": {
        "summary": "已授权设备列表",
        "description": "需要作用域：read:devices。",
        "operationId": "v1_api_v1_devices",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "devices": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/subscription": {
      "get": {
        "summary": "订阅状态与权益",
        "description": "需要作用域：read:subscription。",
        "operationId": "v1_api_v1_subscription",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/orders": {
      "get": {
        "summary": "订单列表（cursor-page/1）",
        "description": "需要作用域：read:orders。",
        "operationId": "v1_api_v1_orders",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每页条数，默认 50，上限 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "上一页返回的 next_cursor，原样回传；不要自行构造",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "contract": {
                      "type": "string",
                      "example": "cursor-page/1"
                    },
                    "resource": {
                      "type": "string",
                      "example": "orders"
                    },
                    "limit": {
                      "type": "integer",
                      "example": 50
                    },
                    "count": {
                      "type": "integer",
                      "example": 12
                    },
                    "has_more": {
                      "type": "boolean",
                      "example": true
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "末页为 null；不透明字符串，原样回传即可"
                    },
                    "snapshot_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "快照时间，翻页期间数据一致"
                    },
                    "orders": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "contract",
                    "resource"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/invoices": {
      "get": {
        "summary": "发票列表（cursor-page/1）",
        "description": "需要作用域：read:invoices。",
        "operationId": "v1_api_v1_invoices",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每页条数，默认 50，上限 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "上一页返回的 next_cursor，原样回传；不要自行构造",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "contract": {
                      "type": "string",
                      "example": "cursor-page/1"
                    },
                    "resource": {
                      "type": "string",
                      "example": "invoices"
                    },
                    "limit": {
                      "type": "integer",
                      "example": 50
                    },
                    "count": {
                      "type": "integer",
                      "example": 12
                    },
                    "has_more": {
                      "type": "boolean",
                      "example": true
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "末页为 null；不透明字符串，原样回传即可"
                    },
                    "snapshot_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "快照时间，翻页期间数据一致"
                    },
                    "invoices": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "contract",
                    "resource"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/submissions": {
      "get": {
        "summary": "插件提交列表（cursor-page/1）",
        "description": "需要作用域：read:submissions。",
        "operationId": "v1_api_v1_submissions",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每页条数，默认 50，上限 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "上一页返回的 next_cursor，原样回传；不要自行构造",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "contract": {
                      "type": "string",
                      "example": "cursor-page/1"
                    },
                    "resource": {
                      "type": "string",
                      "example": "submissions"
                    },
                    "limit": {
                      "type": "integer",
                      "example": 50
                    },
                    "count": {
                      "type": "integer",
                      "example": 12
                    },
                    "has_more": {
                      "type": "boolean",
                      "example": true
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "末页为 null；不透明字符串，原样回传即可"
                    },
                    "snapshot_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "快照时间，翻页期间数据一致"
                    },
                    "submissions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "contract",
                    "resource"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "summary": "列出我的 Webhook",
        "description": "需要作用域：read。每个用户最多 5 个 Webhook。",
        "operationId": "v1_api_v1_webhooks",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "webhooks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "order.paid",
                                "order.refunded",
                                "subscription.expiring",
                                "subscription.expired",
                                "plugin.approved",
                                "plugin.rejected"
                              ]
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "paused"
                            ]
                          },
                          "signing_key_id": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      },
      "post": {
        "summary": "创建 Webhook",
        "description": "需要作用域：read。建议携带 Idempotency-Key，避免网络重试造成重复创建。",
        "operationId": "v1_api_v1_webhooks",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/webhooks/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "查看单个 Webhook",
        "description": "需要作用域：read。",
        "operationId": "v1_api_v1_webhooks__id_",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      },
      "patch": {
        "summary": "修改单个 Webhook",
        "description": "需要作用域：read。",
        "operationId": "v1_api_v1_webhooks__id_",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      },
      "delete": {
        "summary": "删除 Webhook",
        "description": "需要作用域：read。",
        "operationId": "v1_api_v1_webhooks__id_",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "deleted": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/webhooks/{id}/{action}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "action",
          "in": "path",
          "required": true,
          "description": "enable 启用 / disable 停用 / secret 轮换签名密钥",
          "schema": {
            "type": "string",
            "enum": [
              "enable",
              "disable",
              "secret"
            ]
          }
        }
      ],
      "patch": {
        "summary": "启用 / 停用 / 轮换签名密钥",
        "description": "需要作用域：read。轮换 secret 后存在过渡期：旧签名短期内仍可验证，便于无停机切换。",
        "operationId": "v1_api_v1_webhooks__id___action_",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/webhooks/deliveries": {
      "get": {
        "summary": "投递记录",
        "description": "需要作用域：read。",
        "operationId": "v1_api_v1_webhooks_deliveries",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每页条数，默认 50，上限 200",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "event": {
                            "type": "string",
                            "enum": [
                              "order.paid",
                              "order.refunded",
                              "subscription.expiring",
                              "subscription.expired",
                              "plugin.approved",
                              "plugin.rejected"
                            ]
                          },
                          "status": {
                            "type": "string"
                          },
                          "response_status": {
                            "type": "integer",
                            "nullable": true
                          },
                          "attempt": {
                            "type": "integer"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/v1/webhooks/deliveries/{id}/resend": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "手动重投一次投递",
        "description": "需要作用域：read。",
        "operationId": "v1_api_v1_webhooks_deliveries__id__resend",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        },
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "tags": [
          "v1"
        ]
      }
    },
    "/api/developer/overview": {
      "get": {
        "summary": "开发者总览",
        "description": "资料完成度与提交统计。",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "developer"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/developer/profile": {
      "get": {
        "summary": "开发者资料",
        "description": "开发者类型与资料字段。",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "developer"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/developer/submissions": {
      "get": {
        "summary": "我的插件提交",
        "description": "当前登录开发者的提交列表。",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "developer"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "submissions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/developer/submissions/{plugin_key}/{version}/withdraw": {
      "parameters": [
        {
          "name": "plugin_key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "version",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "撤回指定版本的提交",
        "description": "把待审核的提交撤回为草稿。已发布版本不可撤回。",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "developer"
        ],
        "responses": {
          "200": {
            "description": "已撤回",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "withdrawn": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/shared-index/roots": {
      "get": {
        "summary": "列出团队根目录",
        "description": "返回当前用户可读的根目录。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "summary": "创建根目录",
        "description": "在同一团队下创建一个可共享的索引根。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/shared-index/roots/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "查看根目录",
        "description": "返回根目录元数据与当前用户角色。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "summary": "更新根目录",
        "description": "修改可写字段。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/shared-index/roots/{id}/entries": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "浏览/检索条目",
        "description": "带 q 参数时按关键词检索，否则按时间浏览。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "summary": "发布条目",
        "description": "批量写入条目。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/shared-index/roots/{id}/{status_action}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "status_action",
          "in": "path",
          "required": true,
          "description": "pause 暂停 / resume 恢复 / revoke 吊销",
          "schema": {
            "type": "string",
            "enum": [
              "pause",
              "resume",
              "revoke"
            ]
          }
        }
      ],
      "post": {
        "summary": "暂停 / 恢复 / 吊销根目录",
        "description": "生命周期操作。（测试版：字段可能在 v1 内调整）",
        "security": [
          {
            "SessionAuth": []
          }
        ],
        "tags": [
          "shared-index"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/signing-keys/current": {
      "get": {
        "summary": "当前签名公钥",
        "description": "返回生效中的 Ed25519 公钥与已退役公钥列表。公开端点，无需鉴权。",
        "security": [],
        "tags": [
          "signing-keys"
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "enabled": {
                      "type": "boolean"
                    },
                    "algorithm": {
                      "type": "string",
                      "example": "Ed25519"
                    },
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key_id": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "retired"
                            ]
                          },
                          "public_key_base64": {
                            "type": "string"
                          },
                          "public_key_spki_base64": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/signing-keys/verify": {
      "post": {
        "summary": "验证插件包签名",
        "description": "省略 sha256 时按 plugin_key + version 回查插件表取摘要与签名。",
        "security": [],
        "tags": [
          "signing-keys"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plugin_key": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$",
                    "description": "可选，省略则回查"
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{128}$",
                    "description": "可选，省略则用插件表中的签名"
                  },
                  "permissions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "plugin_key",
                  "version"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "验签结果（注意：验签失败也返回 200，看 verified 字段）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    }
                  },
                  "required": [
                    "ok"
                  ],
                  "verified": {
                    "type": "boolean"
                  },
                  "key_id": {
                    "type": "string",
                    "nullable": true
                  },
                  "reason": {
                    "type": "string",
                    "nullable": true
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "活性探测",
        "description": "不读取数据库，只回报本主机当前上线的接口家族。适合部署后自检与监控探活。",
        "security": [],
        "tags": [
          "system"
        ],
        "responses": {
          "200": {
            "description": "服务存活",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "service": {
                      "type": "string",
                      "example": "quickfind-api"
                    },
                    "surfaces": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "v1",
                        "developer",
                        "shared-index",
                        "signing-keys"
                      ]
                    }
                  },
                  "required": [
                    "ok",
                    "service",
                    "surfaces"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "qf_live_ 前缀的 API 密钥"
      },
      "SessionAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "QuickFind 用户登录令牌（JWT）"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "POST 建议携带。同一 Key + 同一请求体重试会回放首次响应；Key 冲突返回 409。",
        "schema": {
          "type": "string",
          "maxLength": 200
        }
      }
    },
    "responses": {
      "Error": {
        "description": "错误响应（统一结构）",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "ok": {
                  "type": "boolean",
                  "example": false
                },
                "error": {
                  "type": "string",
                  "enum": [
                    "api_key_required",
                    "invalid_api_key",
                    "unauthorized",
                    "insufficient_scope",
                    "email_not_verified",
                    "api_not_found",
                    "endpoint_not_found",
                    "unknown_webhook_action",
                    "plugin_version_not_found",
                    "method_not_allowed",
                    "idempotency_conflict",
                    "idempotency_in_progress",
                    "events_required",
                    "unknown_events",
                    "limit_invalid",
                    "limit_out_of_range",
                    "plugin_key_and_version_required",
                    "sha256_unavailable",
                    "rate_limited",
                    "v1_error",
                    "not_configured"
                  ]
                },
                "message": {
                  "type": "string",
                  "description": "人类可读说明，可能随措辞调整，请勿用于分支判断"
                }
              },
              "required": [
                "ok",
                "error"
              ]
            },
            "examples": {
              "missing_key": {
                "value": {
                  "ok": false,
                  "error": "api_key_required",
                  "message": "Authorization: Bearer qf_live_…"
                }
              },
              "bad_scope": {
                "value": {
                  "ok": false,
                  "error": "insufficient_scope",
                  "message": "This API key does not carry the scope required by this endpoint",
                  "required": [
                    "read:orders"
                  ],
                  "missing": [
                    "read:orders"
                  ],
                  "declared": [
                    "read:favorites"
                  ]
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "超出配额",
        "headers": {
          "RateLimit-Scope": {
            "description": "本次计数维度：apikey 或 ip",
            "schema": {
              "type": "string",
              "enum": [
                "apikey",
                "ip"
              ]
            }
          },
          "RateLimit-Limit": {
            "description": "窗口内允许的请求数",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Window-Seconds": {
            "description": "窗口长度（秒）",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Retry-After": {
            "description": "被限流时建议等待的秒数（仅 429 出现）",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "ok": {
                  "type": "boolean",
                  "example": false
                },
                "error": {
                  "type": "string",
                  "example": "rate_limited"
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "apikey",
                    "ip"
                  ]
                },
                "limit": {
                  "type": "integer"
                },
                "window_seconds": {
                  "type": "integer"
                },
                "retry_after": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}