跳转到主要内容

​
欢迎使用 API

Mirobody Health API 提供对健康设备集成、数据检索和 AI 驱动的健康洞察的编程访问。
Base URL: http://localhost:18080 (开发环境) 或 https://your-domain.com (生产环境)

​
API 分类

Pulse API

从 OAuth 提供商和 Apple Health 连接健康设备并检索标准化的健康数据

Chat API

从集成了 MCP 工具的 DeepAgent 和 BaselineAgent 流式获取 AI 响应

MCP 协议

面向 AI agent 的 JSON-RPC 2.0 接口，用于发现和调用工具及资源

​
Base URL

http://localhost:18080

​
身份验证

大多数 API 端点需要使用 Authorization 标头中的 JWT 令牌进行身份验证： 
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:18080/api/v1/pulse/providers

​
获取令牌

令牌通过身份验证端点颁发：
  • 电子邮箱登录: POST /api/v1/user/email/login
  • Google OAuth: POST /api/v1/user/google/login
  • Apple 登录: POST /api/v1/user/apple/login
某些公开端点（如 /api/v1/pulse/providers）可能无需身份验证即可工作，但用户特定的操作始终需要有效的令牌。

​
速率限制

API 请求按用户和提供商进行速率限制：
  • 默认: 每用户每分钟 100 次请求
  • 提供商特定: 因提供商而异（例如 Garmin: 60 次/分钟）
超过速率限制会返回 429 Too Many Requests 响应，并包含 Retry-After 标头。

​
响应格式

所有 API 响应都遵循标准格式： 
{
  "code": 0,
  "msg": "ok",
  "data": {
    // 响应数据
  }
}

​
HTTP 状态码

状态码描述
200成功
400错误请求 - 参数无效
401未授权 - 令牌无效或缺失
403禁止访问 - 权限不足
404未找到 - 资源不存在
429请求过多 - 已超过速率限制
500服务器内部错误

​
常见错误代码

代码描述解决方案
0成功-
-1通用错误检查错误消息
-32000需要身份验证 (MCP)通过 OAuth 流程进行身份验证
-32601未找到方法 (MCP)检查方法名称
-32602参数无效 (MCP)验证参数格式

​
快速上手

1

列出可用提供商

curl http://localhost:18080/api/v1/pulse/providers
返回所有支持的健康设备提供商（Garmin, Whoop, Apple Health 等）
2

链接提供商 (OAuth)

curl -X POST http://localhost:18080/api/v1/pulse/user/providers/link \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_slug": "theta_garmin",
    "platform": "theta",
    "auth_type": "oauth2"
  }'
返回用于用户授权的 OAuth URL
3

与 AI 对话

curl -X POST http://localhost:18080/api/v1/chat/stream \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "我这周走了多少步？",
    "agent": "deep",
    "user_id": "user_123"
  }'
流式传输带有健康数据见解的 AI 响应
4

调用 MCP 工具

curl -X POST http://localhost:18080/mcp \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_health_indicator",
      "arguments": {"keywords": "steps"}
    }
  }'
通过 MCP 协议直接查询健康数据

​
API 端点概览

​
Pulse API (/api/v1/pulse)

端点方法描述
/providersGET列出所有可用提供商
/user/providersGET获取用户已链接的提供商
/user/providers/linkPOST链接新提供商
/user/providers/unlinkPOST取消链接提供商
/{platform}/{provider}/callbackGETOAuth 回调处理器
/{platform}/webhookPOST提供商 Webhook 接收器

​
Chat API (/api/v1/chat)

端点方法描述
/streamPOST流式传输聊天响应 (SSE)
/historyGET获取对话历史记录
/sessionPOST创建/管理会话

​
MCP API (/mcp)

方法描述
initialize握手和能力确认
tools/list列出可用工具
tools/call执行工具
resources/list列出资源
resources/read读取资源

​
文件 API (/api/v1/data)

端点方法描述
/upload-with-processingPOST上传并处理健康文件
/health/dataGET/POST查询/存储健康数据
/uploaded-filesGET列出已上传文件

​
API 版本控制

API 使用基于 URL 的版本控制：
  • 当前版本: /api/v1/...
  • 未来版本: /api/v2/... (如有)
始终使用带版本的端点（/api/v1/...）以确保兼容性。MCP 端点（/mcp）遵循其自身的协议版本控制。

​
Webhooks

Mirobody Health 支持 Webhook，用于从提供商实时更新健康数据： 
POST /{platform}/webhook
Content-Type: application/json

{
  "user_id": "user_123",
  "source": "theta_garmin",
  "timestamp": 1705320600000,
  "timezone": "America/Los_Angeles",
  "data": [
    {
      "type": "steps",
      "value": 10543,
      "unit": "steps",
      "timestamp": 1705320600000
    }
  ]
}
Webhook 在链接 OAuth 提供商时会自动配置。详情请参阅 提供商集成。

​
下一步

Pulse API

连接和管理健康提供商

Chat API

集成 AI 健康助手

MCP 协议

构建 AI agent 集成

示例

查看完整的实现示例