欢迎使用 API
Mirobody Health API 提供可编程访问能力，用于健康设备集成、数据获取以及 AI 驱动的健康洞察。
Base URL: http://localhost:18080（development）或 https://your-domain.com（production）
API 分类
大多数 API endpoints 需要使用 JWT token 进行认证：
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
http://localhost:18080/api/v1/pulse/providers
在开发与测试环境中，部分 endpoints 可能会根据配置允许匿名访问。
速率限制
API 请求会按用户与 Provider 进行限流：
- Default：每位用户每分钟 100 次请求
- Provider-specific：不同 Provider 不同（例如 Garmin：60 req/min）
超过限流会返回 429 Too Many Requests，并带有 Retry-After header。
错误响应
所有 API 错误都遵循统一格式：
{
"error": {
"code": "INVALID_TOKEN",
"message": "The provided access token is invalid or expired",
"details": {
"provider": "theta_garmin",
"timestamp": "2024-01-15T10:30:00Z"
}
}
}
Common Error Codes
| Code | Description | Resolution |
|---|
INVALID_TOKEN | OAuth token 无效或已过期 | 刷新 token 或重新链接账号 |
PROVIDER_NOT_FOUND | Provider 不存在 | 检查 provider slug |
USER_NOT_LINKED | 用户尚未链接该 provider | 先完成 OAuth flow |
RATE_LIMIT_EXCEEDED | 请求过多 | 等待后重试并使用 backoff |
INTERNAL_ERROR | 服务端错误 | 联系支持 |
快速上手
列出可用 providers
curl http://localhost:18080/api/v1/pulse/providers
链接一个 provider
curl "http://localhost:18080/api/v1/pulse/theta/theta_garmin/link?user_id=user_123"
获取健康数据
curl "http://localhost:18080/api/v1/pulse/data?user_id=user_123&provider=theta_garmin"
SDK 与库
from mirobody_client import MirobodyClient
client = MirobodyClient(base_url="http://localhost:18080")
# List providers
providers = await client.pulse.list_providers()
# Link provider
link_url = await client.pulse.link_provider(
provider_slug="theta_garmin",
user_id="user_123"
)
# List providers
curl http://localhost:18080/api/v1/pulse/providers
# Link provider
curl "http://localhost:18080/api/v1/pulse/theta/theta_garmin/link?user_id=user_123"
# Get data
curl "http://localhost:18080/api/v1/pulse/data?user_id=user_123"
SDKs 仍在开发中；目前请使用直接 HTTP 请求，或以上示例作为参考。
API 版本管理
API 使用基于 URL 的版本管理：
- Current：
/api/v1/...
- Future：
/api/v2/...（when available）
请始终使用带版本号的 endpoints 以确保兼容性。
Webhooks（Coming Soon）
订阅实时健康数据更新：
{
"webhook_url": "https://your-app.com/webhooks/health",
"events": ["data.new", "provider.linked"],
"provider": "theta_garmin"
}
下一步
