# 业务 API 说明

业务 API 目录：`/api`（JSON）或 `/api?agent_mode=True`（纯文本）。

每个业务接口都使用原路径加 `agent_mode=True` 返回 `text/plain; charset=utf-8` 的接口说明，包含用途、方法、参数、响应、调用示例和错误。查询值不区分大小写；已有查询参数时使用 `&agent_mode=True`。使用 GET 或 HEAD 读取说明，HEAD 不含正文；说明不查询数据库或对象存储，不要求动态 ID 实际存在。

例如：

- `/api/upload?agent_mode=True`
- `/api/notes/{id}?agent_mode=True`
- `/api/preview?source=%2Fexample.png&agent_mode=True`
- `/studio/api/export/{slug}?agent_mode=True`

业务调用时移除该参数。POST、PUT 等写入方法保持原有行为，不会因该参数变成文档请求。页面正文和 Markdown 兼容接口继续使用原有规则。

Wiki 文档注册表位于 `apps/waterfall-wiki/src/lib/api-documentation.ts`，由各业务路由在 handler 开头调用；目录从同一注册表生成。Studio 文档位于 `apps/studio/src/lib/api-documentation.ts`，随创作站独立部署。