开发者
REST API
Buda 位于 /api/v1 的契约优先 REST API——OpenAPI 规范、Swagger UI，以及一份完整的快速上手示例。
用任何语言调用 Buda。 位于 /api/v1 的 REST API 采用契约优先：每个端点都由一份 oRPC 契约定义，因此 OpenAPI 规范和 Swagger UI 始终与服务端的实际行为保持一致。你可以在后端、CI 任务、非 TypeScript 客户端或生成的 SDK 中使用它。
探索 API
- Swagger UI（
/api/v1/doc）——用你的 API 密钥实时测试调用。 - OpenAPI JSON（
/api/v1/openapi.json）——将它喂给openapi-generator、Postman、Insomnia 或契约测试。
TypeScript 客户端也可以直接从导出的 oRPC 契约生成类型，而不必从 JSON 规范生成。
身份认证
每个受保护的端点都要求把 sk_ API 密钥作为 Bearer 令牌：
curl https://buda.im/api/v1/api-agents \
-H "Authorization: Bearer sk_your_api_key"缺失或无效的密钥会返回 401 Unauthorized。请参阅身份认证来创建和管理密钥。
快速上手
健康检查（无需认证）
curl https://buda.im/api/v1/health{ "status": "ok", "timestamp": "2025-01-01T00:00:00.000Z" }我是谁？
curl https://buda.im/api/v1/users/me \
-H "Authorization: Bearer sk_your_api_key"创建一个基于 Drive 的 Claw（爪）智能体
curl -X POST https://buda.im/api/v1/api-agents \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"spaceId": "YOUR_SPACE_ID",
"name": "Watch Assistant",
"instructions": "Use Drive files as source of truth and keep replies concise."
}'向智能体 Drive 添加知识
curl -X PUT https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/drive/files \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"path": "manuals/reset-device.md",
"content": "# Resetting\n\nHold the crown for 8 seconds.",
"mimeType": "text/markdown"
}'启动一个会话并轮询回复
# 发送一条消息——智能体运行将异步启动（202）
curl -X POST https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "message": "How do I reset my device?", "mode": "chat" }'
# 轮询会话，直到状态变为 completed / waiting_for_input / failed / cancelled
curl https://buda.im/api/v1/api-agents/YOUR_AGENT_ID/sessions/SESSION_ID \
-H "Authorization: Bearer sk_your_api_key"端点分组
整套 API 被组织成几个相互协作的分组，全部位于 /api/v1 之下：
| 分组 | 基础路径 | 作用 |
|---|---|---|
| 系统 | /health、/meta | 存活检查与服务元数据（/health 无需认证）。 |
| 用户 | /users/me | 已认证密钥的所有者。 |
| API Claw（爪） | /api-agents、/spaces、/spaces/{id}/agents、.../drive/files、.../sessions | 创建空间与托管智能体、管理 Drive、运行并读取会话、调度任务。 |
| 嵌入 | .../embed-urls、.../embed-sessions、/embed/chat-sessions/{id} | 短期 iframe URL 与前端可安全使用的令牌。 |
如需完整的请求/响应结构，请使用实时的 Swagger UI 或 OpenAPI JSON。