開發者
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。