docs: suites-help/SDK参考/API-参考.md

suites-help/SDK参考/API-参考.md

@@ -0,0 +1,66 @@
+# API 参考
+
+## 基础地址
+
+```
+https://suites.mercator.cn
+```
+
+## 认证
+
+使用 `Bearer Token` 或 `API Key`：
+
+```bash
+Authorization: Bearer mk_xxxxxxxxxxxxx
+```
+
+API Key 从 https://auth.mercator.cn 获取。
+
+## 套件 API
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| POST | `/api/v1/suites` | 创建套件 |
+| GET | `/api/v1/suites` | 套件列表 |
+| GET | `/api/v1/suites/search?q=` | 搜索套件 |
+| GET | `/api/v1/suites/{id}` | 套件详情 |
+| PATCH | `/api/v1/suites/{id}` | 更新套件 |
+| DELETE | `/api/v1/suites/{id}` | 删除套件 |
+| POST | `/api/v1/suites/{id}/execute` | 执行套件 |
+
+## 任务 API
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/v1/task/next` | 拉取待执行任务（长轮询）|
+| PATCH | `/api/v1/task/{id}/status` | 更新任务状态 |
+| GET | `/api/v1/task/{id}` | 查询任务详情 |
+
+## 脚本 API
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| POST | `/api/v1/scripts` | 注册脚本 |
+| GET | `/api/v1/scripts` | 脚本列表 |
+| GET | `/api/v1/scripts/search?q=` | 搜索脚本 |
+| GET | `/api/v1/scripts/{id}` | 脚本详情 |
+| PATCH | `/api/v1/scripts/{id}` | 更新脚本 |
+
+## 完整文档
+
+自动生成的全量 API 文档：
+[https://suites.mercator.cn/docs](https://suites.mercator.cn/docs)
+
+## 错误码
+
+| 状态码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 400 | 请求参数错误 |
+| 401 | 未认证或 API Key 无效 |
+| 403 | 权限不足 |
+| 404 | 资源不存在 |
+| 409 | 资源冲突 |
+| 422 | 参数校验失败 |
+| 500 | 服务器内部错误 |