Skip to main content

​
Welcome to the API

The Mirobody Health API provides programmatic access to health device integrations, data retrieval, and AI-powered health insights.
Base URL: http://localhost:18080 (development) or https://your-domain.com (production)

​
API Categories

Pulse API

Connect health devices and retrieve standardized health data

Chat API

Interact with AI health assistants

MCP Protocol

JSON-RPC interface for AI agents and tools

​
Authentication

Most API endpoints require authentication using JWT tokens: 
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:18080/api/v1/pulse/providers
For development and testing, some endpoints may allow unauthenticated access based on configuration.

​
Rate Limiting

API requests are rate-limited per user and per provider:
  • Default: 100 requests per minute per user
  • Provider-specific: Varies by provider (e.g., Garmin: 60 req/min)
Exceeding rate limits returns a 429 Too Many Requests response with a Retry-After header.

​
Error Responses

All API errors follow a consistent format: 
{
  "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

CodeDescriptionResolution
INVALID_TOKENOAuth token invalid or expiredRefresh token or relink account
PROVIDER_NOT_FOUNDProvider doesn’t existCheck provider slug
USER_NOT_LINKEDUser hasn’t linked providerComplete OAuth flow first
RATE_LIMIT_EXCEEDEDToo many requestsWait and retry with backoff
INTERNAL_ERRORServer-side errorContact support

​
Quick Start

1

List available providers

curl http://localhost:18080/api/v1/pulse/providers
2

Link a provider

curl "http://localhost:18080/api/v1/pulse/theta/theta_garmin/link?user_id=user_123"
3

Retrieve health data

curl "http://localhost:18080/api/v1/pulse/data?user_id=user_123&provider=theta_garmin"

​
SDKs and Libraries

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"
)
SDKs are under development. For now, use direct HTTP requests or the examples above as reference.

​
API Versioning

The API uses URL-based versioning:
  • Current: /api/v1/...
  • Future: /api/v2/... (when available)
Always use the versioned endpoints to ensure compatibility.

​
Webhooks (Coming Soon)

Subscribe to real-time health data updates: 
{
  "webhook_url": "https://your-app.com/webhooks/health",
  "events": ["data.new", "provider.linked"],
  "provider": "theta_garmin"
}

​
Next Steps

Pulse API

Connect and manage health providers

Chat API

Integrate AI health assistants

MCP Protocol

Build AI agent integrations

Examples

See complete implementation examples