API Reference

GumboMax provides RESTful APIs covering knowledge base retrieval, SKILL Market, AI Workbench file management, and draft storage. This is the complete reference.

⚡ AI Quick Start — Ready in 3 minutes with your Key

Self-check Key: POST /v1/auth/key-status Header: X-Api-Key returns all subsystem connectivity status (standard entry)
Fallback verify: GET /v1/knowledge?action=agents&key=YOUR_KEY returns the agent list if Key is valid
Browse SKILL Market: GET /v1/skills fetches all available SKILL cards (code, intro, tier)
Get SKILL body: POST /v1/knowledge?action=start&key=KEY body: {"agent":"03-deep-research","task":"deep-research-report"} returns session + first fragment
Save to Drafts: POST /v1/generator/save-draft Header: X-Api-Key body: {"productCode":"...","name":"...","tier":"...","userEmail":""}
Manage files: GET/POST /v1/profile/projects + /v1/profile/projects/{id}/files Header: X-Api-Key

These steps cover all core read (knowledge/market) and write (drafts/files) scenarios. Full endpoint table below.

Base URL

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

All APIs use application/json format.

Authentication (Dual Channel)

Channel 1: URL Query Parameter (read-only)

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

Use for: knowledge retrieval, SKILL Market browsing. Append ?key= to the URL.

Channel 2: X-Api-Key Header (read + write)

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

Use for: knowledge retrieval, SKILL Market, Workbench file management, draft storage. This is the recommended method.

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

Coming soon: Authorization: Bearer JWT support will be added in a future version.

Get Your API Key

After subscribing, your API Key will be sent to your registered email. Self-service Key management in the AI Workbench is coming soon. You can create multiple Keys for different AIs under one subscription — all Keys share the same plan permissions.

Permissions

Plan	Knowledge Base Access	SKILL Market Visibility	Workbench Features
Free (7-day trial)	Full knowledge base (7 days)	All SKILL card intros + Free/Base full codes	File management + Drafts
AiEA Base	Base knowledge domain	All SKILL card intros + Base full codes	File management + Drafts
AiCOO Pro	Base + Pro knowledge domains	All SKILL card intros + Pro and below full codes	File management + Drafts
AiCOO Ultra	All knowledge domains	All SKILL card full codes	File management + Drafts (admin can use Generator)

SKILL Code Visibility: SKILL cards are visible to everyone (name, intro, scenarios). However, the product code is only shown in full for SKILLs within your plan tier. Codes beyond your tier display as ****@v?. This is server-side filtering, not frontend hiding.

Rate Limits

Endpoint	Rate Limit	Notes
Knowledge API	60 req/min	Knowledge retrieval, per-key
Profile / Files API	60 req/min	Workbench file management
Generator API	30 req/min	Draft saves
Contact API	10 req/min	Contact form, no auth required

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Response Format

Success response:

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

Error response:

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

Error Codes

HTTP	Code	Description
400	`INVALID_PARAMS`	Missing or invalid parameters
400	`invalid_action`	knowledge action not in valid list (response lists available values)
400	`product_code required`	search/execute missing product_code parameter
400	`agent and task required`	start session missing agent or task (note: must use POST + JSON body)
401	`UNAUTHORIZED`	Missing or invalid API Key
402	`subscription_required`	Active subscription required
403	`FORBIDDEN`	Valid Key but insufficient permissions
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Internal server error

All Endpoints

☁️ Knowledge Base

Method	Endpoint	Auth	Description
GET	`/v1/knowledge?action=agents&key=`	?key=	List available Agents
POST	`/v1/knowledge?action=start&key=`	?key=	Start knowledge session. Body: `{"agent":"03","task":"name"}`, returns session + fragment content + totalSteps. AI can directly read and execute.
POST	`/v1/knowledge?action=next&key=`	?key=	Get next fragment. Body: `{"session":"uuid"}`
POST	`/v1/knowledge?action=search&key=`	?key=	Search SKILL. Body: `{"product_code":"AICOO:..."}` Parameter name is product_code, not code
POST	`/v1/knowledge?action=execute&key=`	?key=	Step-by-step execution gateway. Body: `{"product_code":"...","step":0}` → each call returns 1 instruction only, returns done:true when complete

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

Search endpoint note: may return found:false even if the SKILL is live. If search fails, use GET /v1/skills for the complete catalog. We are working on expanding search index coverage.

🛒 SKILL Market

Method	Endpoint	Auth	Description
GET	`/v1/skills`	None (optional X-Api-Key or ?key= for full codes)	List all published SKILL cards. Supports `?dept=` `?tier=` `?q=` filters. Codes beyond your tier display as `****@v?`
GET	`/v1/skills/{code}`	None (optional auth same as above)	Get single SKILL detail (name/intro/scenarios/benefits/tier/difficulty)

🧠 AI Workbench · File Management

Method	Endpoint	Auth	Description
GET	`/v1/profile/projects`	X-Api-Key or JWT	List all folders. Returns `[{id, title, category, parent_id}]`
POST	`/v1/profile/projects`	X-Api-Key or JWT	Create folder. Body: `{"title":"name","category":"","parent_id":null}`
PUT	`/v1/profile/projects/{id}`	X-Api-Key or JWT	Rename folder
DELETE	`/v1/profile/projects/{id}`	X-Api-Key or JWT	Delete folder
GET	`/v1/profile/projects/{id}/files`	X-Api-Key or JWT	List files in folder
GET	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key or JWT	Read file content
POST	`/v1/profile/projects/{id}/files`	X-Api-Key or JWT	Create file. Body: `{"filename":"name.md","content":"body"}`
PUT	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key or JWT	Update file content
DELETE	`/v1/profile/projects/{id}/files/{fid}`	X-Api-Key or JWT	Delete file

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

📝 Drafts & Self-Check

Method	Endpoint	Auth	Description
POST	`/v1/auth/key-status`	X-Api-Key	Key self-check endpoint. Returns subsystem connectivity (knowledge/skills/profile/generator). AI should call this first after receiving a Key to confirm permissions.
POST	`/v1/generator/save-draft`	X-Api-Key	Save to Drafts. Body: `{"productCode":"...","name":"...","intro":"...","tier":"free","userEmail":""}`. All valid subscription Keys can call this.
GET	`/v1/profile/skills/drafts`	X-Api-Key or JWT	List drafts
DELETE	`/v1/profile/skills/drafts/{fid}`	X-Api-Key or JWT	Delete draft

👤 Profile & Others

Method	Endpoint	Auth	Description
GET	`/v1/profile`	X-Api-Key or JWT	Get profile (plan/storage/subscription status)
GET	`/v1/gmcoo`	X-Api-Key	System health check
POST	`/v1/contact`	None	Submit ticket. Body: `{"name":"","email":"","message":""}`

Complete Examples

Scenario: AI with Key, full workflow — browse SKILLs → get body → save draft → create folder → write file

# 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内容..."}'

Versioning

Current API version is v1, identified by the URL path (/v1/). Backward compatibility is maintained within the same major version.

Next Steps

Quick Start — Get started in 10 minutes
Product — Learn about AiCOO architecture
Pricing — Choose your plan