API 参考

GumboMax 提供 RESTful API，覆盖知识库检索、经验广场、AI 工作台文件管理、草稿箱等功能。本文为完整参考。

⚡ AI 接入速查 — 拿到 Key 3 分钟上手

验证 Key 自检：POST /v1/auth/key-status Header: X-Api-Key → 返回所有子系统连通性状态（最标准的自检入口）
备用验证：GET /v1/knowledge?action=agents&key=YOUR_KEY → 返回 agents 列表即 Key 有效
浏览经验广场：GET /v1/skills → 获取所有可调用商品卡（含编码、简介、套餐）
取商品正文：POST /v1/knowledge?action=start&key=KEY body: {"agent":"03-deep-research","task":"deep-research-report"} → 逐片取回
存入草稿箱：POST /v1/generator/save-draft Header: X-Api-Key body: {"productCode":"...","name":"...","tier":"...","userEmail":""}
管理文件：GET/POST /v1/profile/projects + /v1/profile/projects/{id}/files Header: X-Api-Key

以上步骤覆盖读（知识库/广场）、写（草稿箱/文件管理）全部核心场景。完整端点见下表。

Base URL

https://gcs-watchdog-ai.com/v1

所有 API 使用 application/json 格式。

认证方式（双通道）

通道 1：URL 查询参数（读操作）

curl "https://gcs-watchdog-ai.com/v1/knowledge?action=agents&key=YOUR_API_KEY"

适用于：知识库检索、经验广场浏览。在 URL 后附加 ?key= 参数即可。

通道 2：X-Api-Key 请求头（读+写操作）

curl -H "X-Api-Key: YOUR_API_KEY" "https://gcs-watchdog-ai.com/v1/profile/projects"

适用于：知识库检索、经验广场浏览、工作台文件管理、草稿箱写入。是推荐方式。

两种方式的区别：
?key= 查询参数仅支持读操作。X-Api-Key 请求头支持全部操作（读 + 写），是推荐方式。把 Key 给你的 AI 时，告诉它用这个请求头即可访问全部权限范围内的功能。

未来版本将支持 Authorization: Bearer JWT 方式，届时会通过更新日志通知。

获取 API Key

订阅完成后，API Key 通过邮件发送至你的注册邮箱。后续版本将支持在 AI 工作台自助查看和管理 Key。同一个套餐可以创建多把 Key，给不同 AI 使用——所有 Key 共享套餐权限范围。

权限说明

套餐	知识库访问	经验广场可见	工作台功能
Free（7天试用）	全量知识库（7天）	全部商品卡介绍 + Free/Base 完整编码	文件管理 + 草稿箱
AiEA Base	Base 知识域	全部商品卡介绍 + Base 完整编码	文件管理 + 草稿箱
AiCOO Pro	Base + Pro 知识域	全部商品卡介绍 + Pro 及以下完整编码	文件管理 + 草稿箱
AiCOO Ultra	全部知识域	全部商品卡完整编码	文件管理 + 草稿箱（管理员可用编码器）

商品码可见性：经验广场的商品卡对所有人可见（含名称、简介、场景）。但 商品编码（code） 只对你套餐等级范围内的商品完整显示，超出范围的商品码显示为 ****@v?。这是后端过滤，不是前端隐藏。

限流策略

端点类别	速率限制	说明
Knowledge API	60 次 / 分钟	知识库检索，按 Key 隔离
Profile / Files API	60 次 / 分钟	工作台文件管理
Generator API	30 次 / 分钟	草稿保存
Contact API	10 次 / 分钟	联系表单，无需认证

超出限流返回 429 Too Many Requests，响应头含 Retry-After。

通用响应格式

成功响应：

{"ok": true, /* ...业务数据 */}

错误响应：

{"ok": false, "error": "ERROR_CODE"}

错误码

HTTP	错误码	说明
400	`INVALID_PARAMS`	请求参数缺失或格式错误
400	`invalid_action`	knowledge action 不在有效列表中（响应会列出可用值）
400	`product_code required`	search/execute 缺少 product_code 参数
400	`agent and task required`	start session 缺少 agent 或 task（注意：必须 POST + JSON body）
401	`UNAUTHORIZED`	未提供 API Key 或 Key 无效
402	`subscription_required`	需要有效订阅
403	`FORBIDDEN`	Key 有效但权限不足
404	`NOT_FOUND`	请求的资源不存在
429	`RATE_LIMITED`	请求过于频繁
500	`INTERNAL_ERROR`	服务器内部错误

全部端点一览

☁️ 云端知识库

方法	端点	认证	说明
GET	`/v1/knowledge?action=agents&key=`	?key=	列出可用 Agent
POST	`/v1/knowledge?action=start&key=`	?key=	启动知识库会话。Body: `{"agent":"03","task":"name"}`，返回 session + 碎片 content + totalSteps。可用于 AI 直接读取执行正文。
POST	`/v1/knowledge?action=next&key=`	?key=	获取下一片碎片。Body: `{"session":"uuid"}`
POST	`/v1/knowledge?action=search&key=`	?key=	搜索 SKILL。Body: `{"product_code":"AICOO:..."}` 注意：参数名是 product_code，不是 code
POST	`/v1/knowledge?action=execute&key=`	?key=	逐步执行网关。Body: `{"product_code":"...","step":0}` → 每步只返回1条指令，完成后返回 done:true

start / next / search / execute 四个 action 都必须用 POST + JSON body！ GET 请求会报 agent and task required。
agents 可以用 GET。

search 端点注意：可能返回 found:false 但商品确实在架。如果 search 搜不到，用 GET /v1/skills 拉全量目录确认。我们正在修复 search 索引覆盖范围。

🛒 经验广场

方法	端点	认证	说明
GET	`/v1/skills`	无需（可选 X-Api-Key 或 ?key= 获取完整编码）	列出全部上架商品。支持 `?dept=` `?tier=` `?q=` 过滤。无认证时超出套餐的商品码显示为 `****@v?`
GET	`/v1/skills/{code}`	无需（可选认证同上）	获取单个商品详情（名称/简介/场景/收益/套餐/难度）

🧠 AI 工作台 · 文件管理

方法	端点	认证	说明
GET	`/v1/profile/projects`	X-Api-Key 或 JWT	列出所有文件夹。返回 `[{id, title, category, parent_id}]`
POST	`/v1/profile/projects`	X-Api-Key 或 JWT	创建文件夹。Body: `{"title":"名","category":"","parent_id":null}`
PUT	`/v1/profile/projects/{id}`	X-Api-Key 或 JWT	重命名文件夹
DELETE	`/v1/profile/projects/{id}`	X-Api-Key 或 JWT	删除文件夹
GET	`/v1/profile/projects/{id}/files`	X-Api-Key 或 JWT	列出文件夹内所有文档
GET	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key 或 JWT	读取单个文档全文
POST	`/v1/profile/projects/{id}/files`	X-Api-Key 或 JWT	创建文档。Body: `{"filename":"名.md","content":"正文"}`
PUT	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key 或 JWT	更新文档内容
DELETE	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key 或 JWT	删除文档

数据模型概念映射：
文件夹 = project（API 里叫 project，前端 UI 叫「文件夹」）
文档 = file（API 里叫 file，前端 UI 叫「文档」）
根目录 = parent_id: null
字段注意：写入用 content，读回字段叫 content_text

📝 草稿箱 & 自检

方法	端点	认证	说明
POST	`/v1/auth/key-status`	X-Api-Key	Key 自检端点。返回各子系统连通性状态（knowledge/skills/profile/generator）。AI 拿 Key 后第一步调用此端点确认权限范围。
POST	`/v1/generator/save-draft`	X-Api-Key	存入草稿箱。Body: `{"productCode":"...","name":"...","intro":"...","tier":"free","userEmail":""}`。所有有效订阅 Key 均可调用。
GET	`/v1/profile/skills/drafts`	X-Api-Key 或 JWT	读取草稿箱列表
DELETE	`/v1/profile/skills/drafts/{fid}`	X-Api-Key 或 JWT	删除草稿

👤 个人资料 & 其它

方法	端点	认证	说明
GET	`/v1/profile`	X-Api-Key 或 JWT	获取个人资料（套餐/存储用量/订阅状态）
GET	`/v1/gmcoo`	X-Api-Key	系统状态检查
POST	`/v1/contact`	无需	提交工单。Body: `{"name":"","email":"","message":""}`

完整调用示例

场景：AI 拿到 Key，独立完成「查商品→取正文→存草稿→建文件夹→写文件」全流程

# 0. 你的 Key
KEY="YOUR_API_KEY"

# 1. 自检 Key（推荐第一步）
curl -X POST "https://gcs-watchdog-ai.com/v1/auth/key-status" -H "Content-Type: application/json" -H "X-Api-Key: $KEY"

# 2. 浏览经验广场
curl -H "X-Api-Key: $KEY" "https://gcs-watchdog-ai.com/v1/skills"

# 3. 取商品详情
curl "https://gcs-watchdog-ai.com/v1/skills/AICOO%3AMKT-RESEARCH%3Adeep-research-report%40v1"

# 4. 取商品正文（POST + body）
curl -X POST "https://gcs-watchdog-ai.com/v1/knowledge?action=start&key=$KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":"03-deep-research","task":"deep-research-report"}'

# 5. 存入草稿箱
curl -X POST "https://gcs-watchdog-ai.com/v1/generator/save-draft" \
  -H "Content-Type: application/json" -H "X-Api-Key: $KEY" \
  -d '{"productCode":"AICOO:MKT-RESEARCH:deep-research-report@v1","name":"数据调研","intro":"多源验证","tier":"free","userEmail":""}'

# 6. 创建文件夹
curl -X POST "https://gcs-watchdog-ai.com/v1/profile/projects" \
  -H "Content-Type: application/json" -H "X-Api-Key: $KEY" \
  -d '{"title":"我的项目","category":"","parent_id":null}'

# 7. 写文档
curl -X POST "https://gcs-watchdog-ai.com/v1/profile/projects/123/files" \
  -H "Content-Type: application/json" -H "X-Api-Key: $KEY" \
  -d '{"filename":"笔记.md","content":"# 笔记\n内容..."}'

版本说明

当前 API 版本 v1。版本通过 URL 路径标识（/v1/）。同主版本号下保持向后兼容。API 变更通过更新日志公示。

下一步

快速开始 — 10 分钟上手 AiCOO
产品介绍 — 了解 AiCOO 系统架构
套餐对比 — 选择适合你的方案