全部端点一览
四个家族共 24 个端点。下表为完整清单，含 HTTP 方法、所需作用域与稳定性标记；常用端点附请求/响应说明。
/api/v1稳定
Bearer 密钥鉴权。列表端点统一使用 cursor-page/1 分页（默认 50 条、上限 200 条）。
| 方法 | 路径 | 作用域 | 说明 |
|---|---|---|---|
| GET | /api/v1/me | 无需 | 当前密钥身份、配额与权限概览 |
| GET | /api/v1/usage | read:usage | 近 7 天用量与限流命中统计 |
| GET | /api/v1/favorites | read:favorites | 收藏列表 |
| GET | /api/v1/history | read:history | 搜索历史 |
| GET | /api/v1/devices | read:devices | 已授权设备列表 |
| GET | /api/v1/subscription | read:subscription | 订阅状态与权益 |
| GET | /api/v1/orders | read:orders | 订单列表（cursor-page/1） |
| GET | /api/v1/invoices | read:invoices | 发票列表（cursor-page/1） |
| GET | /api/v1/submissions | read:submissions | 插件提交记录（cursor-page/1） |
| GET POST | /api/v1/webhooks | read | Webhook 列表 / 创建（POST 建议带 Idempotency-Key） |
| GET PATCH DELETE | /api/v1/webhooks/{id} | read | 查看 / 修改 / 删除单个 Webhook |
| PATCH | /api/v1/webhooks/{id}/{enable|disable|secret} | read | 启用 / 停用 / 轮换签名密钥 |
| GET | /api/v1/webhooks/deliveries | read | 投递记录（含状态与响应码） |
| POST | /api/v1/webhooks/deliveries/{id}/resend | read | 手动重投指定事件 |
/api/developer稳定
用户会话 JWT 鉴权（不是 API 密钥）。面向插件开发者本人查询提交物与开发者资料。
| 方法 | 路径 | 鉴权方式 | 说明 |
|---|---|---|---|
| GET | /api/developer/overview | 会话 JWT | 开发者总览：资料完成度与提交统计 |
| GET | /api/developer/profile | 会话 JWT | 开发者资料 |
| GET | /api/developer/submissions | 会话 JWT | 我的插件提交列表 |
| POST | /api/developer/submissions/{plugin_key}/{version}/withdraw | 会话 JWT | 撤回指定版本的提交 |
/api/shared-index测试版
用户会话 JWT + 团队门。团队共享索引：创建根目录、发布条目、检索与生命周期管理。
| 方法 | 路径 | 鉴权方式 | 说明 |
|---|---|---|---|
| GET POST | /api/shared-index/roots | 会话 + 团队 | 根目录列表 / 创建 |
| GET PATCH | /api/shared-index/roots/{id} | 会话 + 团队 | 查看 / 更新根目录 |
| GET POST | /api/shared-index/roots/{id}/entries | 会话 + 团队 | 发布条目 / 浏览（带 q 参数即检索） |
| POST | /api/shared-index/roots/{id}/{pause|resume|revoke} | 会话 + 团队 | 暂停 / 恢复 / 吊销根目录 |
/api/signing-keys稳定
公开家族，无需鉴权。客户端可自行获取公钥并验证插件包签名，不依赖服务端代验。
| 方法 | 路径 | 鉴权方式 | 说明 |
|---|---|---|---|
| GET | /api/signing-keys/current | 公开 | 当前生效与已退役的签名公钥（含 key_id） |
| POST | /api/signing-keys/verify | 公开 | 服务端辅助验签（也可本地用公钥自验） |
常用端点详解（v1）
下表之外的端点遵循同一套约定：只读、无请求体、返回统一结构。
返回当前密钥绑定的账号、密钥指纹、生效作用域与配额。无需任何作用域，适合作为接入后的第一个探活调用。
- quota · 配额结构
- 含 per_minute / per_day 限额与已用计数，随响应实时返回。
订单列表。响应遵循 cursor-page/1 契约：带 limit、has_more 与 next_cursor；翻页时把 next_cursor 原样作为 cursor 查询参数传入，不要在客户端自行推算 offset。
- limit · 可选，整数
- 每页条数，默认 50、上限 200；超限返回 422 limit_out_of_range。
- cursor · 可选，字符串
- 上一页返回的 next_cursor。
创建一个 Webhook 订阅。回调地址会被解析并做可达性预检，事件类型必须在白名单内。建议携带 Idempotency-Key，避免超时重试造成重复创建。
- url · 必填
- 回调地址（HTTPS），需可解析且端口可达。
- events · 必填，数组
- 事件类型，取值见 Webhook 页的事件表；含未知值返回 422 unknown_events。
- description · 可选
- 便于你自己识别的备注。
按时间倒序返回投递记录，每条含事件类型、响应码、第几次尝试与创建时间。失败投递可调用 resend 手动重投。
- limit · 可选，整数
- 每页条数，默认 50、上限 200。
验签端点详解
校验插件包签名。提供 sha256、plugin_key、version 与 signature；若省略 sha256，服务端会按 plugin_key + version 从插件表回查。返回 verified 布尔与签名所用 key_id。
- sha256 · 可选，64 位十六进制
- 省略时按 plugin_key + version 回查插件表。
- plugin_key / version · 必填
- 插件标识与版本号。
- signature · 可选，128 位十六进制
- Ed25519 签名；省略且可回查时使用插件表中的签名。
签名不匹配是「正常结论」而不是请求错误，所以返回 200 + verified: false（附 reason）。只有找不到插件记录（404）、参数缺失（422）或数据源故障（502/503）才用错误码。