OpenAPI REST API
使用 Hono 构建的外部 REST API 与自动生成的 OpenAPI 文档
OpenAPI REST API
Buda 提供基于 Hono 构建的 REST API，并自动生成 OpenAPI 文档。适合以下场景：
- 外部集成（移动应用、第三方服务）
- 从自己的产品调用 Buda Agent
- Webhooks 与回调
- 非 TypeScript 客户端
tRPC vs REST：Next.js 前端使用 tRPC（类型安全、性能更好），外部客户端使用 REST API。
API 文档访问方式
1. Swagger UI（/api/v1/doc）
经典的交互式 API 文档，可直接在浏览器中测试 API 调用。
https://buda.im/api/v1/doc打开 Swagger UI →
2. OpenAPI JSON（/api/v1/openapi.json）
原始 OpenAPI 3.0 规范，适用于：
- 使用
openapi-generator生成 SDK - 导入 Postman、Insomnia 等 API 客户端
- CI/CD 验证和契约测试
https://buda.im/api/v1/openapi.json查看 OpenAPI JSON →
3. API Reference（Fumadocs 集成）
集成到文档站点的美观、可搜索的 API 参考文档。
API Reference 从 OpenAPI Schema 自动生成。运行 pnpm openapi:generate 可更新文档。
认证
Buda REST API 使用 API Key 认证。在请求头中传入：
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://buda.im/api/v1/agent-sessions请把 API Key 当作生产环境密钥管理：不要硬编码到前端，泄露后立即轮换，测试与正式环境分开使用。
API Key 可在控制台的 设置 → API Keys 中创建和管理。
快速开始
健康检查
curl https://buda.im/api/v1/health响应：
{
"status": "ok",
"timestamp": "2025-01-01T00:00:00.000Z",
"version": "1.0.0"
}获取 Agent 会话列表
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://buda.im/api/v1/agent-sessions