REST API

Simple HTTP API for accessing your health data from any application. No MCP required.

Base URL

https://wellpipe.io/api/v1/health

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Wellpipe dashboard.

Query Parameters

Parameter	Type	Required	Default	Description
type	string	No	summary	Data type to fetch
days	number	No	7	Number of days (1-90)
start_date	string	No	-	ISO 8601 date (alternative to days)
end_date	string	No	-	ISO 8601 date (alternative to days)

Type Values

Type	Description
summary	Overview of sleep, recovery, and workouts
sleep	Sleep sessions with stages and scores
recovery	Recovery scores, HRV, and readiness
workout	Workout activities and strain
cycle	Physiological cycles (24-hour periods)
profile	User profile and body measurements

Examples

Get Weekly Summary

curl "https://wellpipe.io/api/v1/health?type=summary&days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Sleep Data

curl "https://wellpipe.io/api/v1/health?type=sleep&days=14" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Recovery Data

curl "https://wellpipe.io/api/v1/health?type=recovery&days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Specific Date Range

curl "https://wellpipe.io/api/v1/health?type=workout&start_date=2024-12-01&end_date=2024-12-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

Responses are JSON. The structure depends on the type parameter.

Summary Response

{
  "period": {
    "start": "2024-12-14T00:00:00.000Z",
    "end": "2024-12-21T00:00:00.000Z",
    "days": 7
  },
  "sleep": {
    "average_duration_hours": 7.2,
    "average_performance": 88,
    "average_efficiency": 92
  },
  "recovery": {
    "average_score": 65,
    "average_hrv": 42,
    "average_rhr": 52
  },
  "strain": {
    "total": 45.3,
    "average_daily": 6.5,
    "workout_count": 5
  }
}

Sleep Response

{
  "records": [
    {
      "id": "abc-123",
      "start": "2024-12-20T22:30:00.000Z",
      "end": "2024-12-21T06:45:00.000Z",
      "duration_hours": 8.25,
      "score": {
        "performance": 92,
        "efficiency": 95,
        "consistency": 88
      },
      "stages": {
        "light_hours": 3.5,
        "deep_hours": 1.8,
        "rem_hours": 2.1,
        "awake_hours": 0.85
      },
      "respiratory_rate": 14.8
    }
  ],
  "count": 7
}

Recovery Response

{
  "records": [
    {
      "cycle_id": "xyz-789",
      "date": "2024-12-21",
      "score": 72,
      "hrv": 45,
      "resting_heart_rate": 51,
      "spo2": 96.5,
      "skin_temp_celsius": 33.2
    }
  ],
  "count": 7
}

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

404 Not Found

{
  "error": "not_found",
  "message": "No health provider connected"
}

429 Rate Limited

{
  "error": "rate_limited",
  "message": "Monthly request limit exceeded",
  "limit": 1000,
  "reset": "2025-01-01T00:00:00.000Z"
}

Rate Limits

Plan	Requests/Month
Free	1,000
Pro	Unlimited

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2025-01-01T00:00:00.000Z

OpenAPI Specification

Full OpenAPI 3.1 specification available at:

https://wellpipe.io/openapi.json

Use this to generate client libraries or import into tools like Postman.

Code Examples

JavaScript (fetch)

const response = await fetch(
  'https://wellpipe.io/api/v1/health?type=summary&days=7',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);

Python (requests)

import requests

response = requests.get(
    'https://wellpipe.io/api/v1/health',
    params={'type': 'summary', 'days': 7},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
print(data)

cURL

curl "https://wellpipe.io/api/v1/health?type=summary&days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

1. Cache responses - Health data doesn't change frequently. Cache for 15-30 minutes.
2. Use appropriate date ranges - Only fetch what you need.
3. Handle rate limits - Check X-RateLimit-Remaining and back off if low.
4. Secure your API key - Never expose it in client-side code or version control.