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 from OAuth providers and Apple Health

Chat API

Stream AI responses from DeepAgent and BaselineAgent with MCP tool integration

MCP Protocol

JSON-RPC 2.0 interface for AI agents to discover and call tools and resources

​
Base URLs

http://localhost:18080

​
Authentication

Most API endpoints require authentication using JWT tokens in the Authorization header: 
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:18080/api/v1/pulse/providers

​
Obtaining Tokens

Tokens are issued through the authentication endpoints:
  • Email Login: POST /api/v1/user/email/login
  • Google OAuth: POST /api/v1/user/google/login
  • Apple Sign In: POST /api/v1/user/apple/login
Some public endpoints (like /api/v1/pulse/providers) may work without authentication, but user-specific operations always require valid tokens.

​
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.

​
Response Format

All API responses follow a standard format: 
{
  "code": 0,
  "msg": "ok",
  "data": {
    // Response data here
  }
}

​
HTTP Status Codes

StatusDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Common Error Codes

CodeDescriptionResolution
0Success-
-1General errorCheck error message
-32000Auth required (MCP)Authenticate via OAuth flow
-32601Method not found (MCP)Check method name
-32602Invalid params (MCP)Verify parameter format

​
Quick Start

1

List available providers

curl http://localhost:18080/api/v1/pulse/providers
Returns all supported health device providers (Garmin, Whoop, Apple Health, etc.)
2

Link a provider (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"
  }'
Returns OAuth URL for user authorization
3

Chat with AI

curl -X POST http://localhost:18080/api/v1/chat/stream \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How many steps did I take this week?",
    "agent": "deep",
    "user_id": "user_123"
  }'
Streams AI response with health data insights
4

Call MCP tools

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"}
    }
  }'
Directly query health data via MCP protocol

​
API Endpoints Overview

​
Pulse API (/api/v1/pulse)

EndpointMethodDescription
/providersGETList all available providers
/user/providersGETGet user’s linked providers
/user/providers/linkPOSTLink a new provider
/user/providers/unlinkPOSTUnlink a provider
/{platform}/{provider}/callbackGETOAuth callback handler
/{platform}/webhookPOSTProvider webhook receiver

​
Chat API (/api/v1/chat)

EndpointMethodDescription
/streamPOSTStream chat response (SSE)
/historyGETGet conversation history
/sessionPOSTCreate/manage sessions

​
MCP API (/mcp)

MethodDescription
initializeHandshake and capabilities
tools/listList available tools
tools/callExecute a tool
resources/listList resources
resources/readRead a resource

​
File API (/api/v1/data)

EndpointMethodDescription
/upload-with-processingPOSTUpload and process health files
/health/dataGET/POSTQuery/store health data
/uploaded-filesGETList uploaded files

​
API Versioning

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

​
Webhooks

Mirobody Health supports webhooks for real-time health data updates from providers: 
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
    }
  ]
}
Webhooks are automatically configured when linking OAuth providers. See Provider Integration for details.

​
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