Whoop Integration

Interact with the Whoop API to fetch and analyze recovery, strain, sleep, HRV, and workout data.

Quick Start

First-time Setup

Prerequisites:

• Python 3.7+
• requests library: pip install requests

Step 1: Create Whoop Developer App

1. Go to https://app.whoop.com/ → Settings → Developer
2. Click "Create Application"
3. Fill in the required fields:
   • Application Name: Your choice (e.g., "Personal Whoop Assistant")
   • Privacy Policy URL: You need a public URL (see options below)
   • Redirect URI: You need a callback URL (see options below)
   • Webhook URL: Leave blank (optional for basic usage)
4. Save your Client ID and Client Secret (keep these private!)

Privacy Policy & Redirect URI Options:

Option A - Quick GitHub Pages Setup:

1. Create a GitHub repo (e.g., whoop-oauth)
2. Add the privacy/redirect HTML files from references/oauth-pages/
3. Enable GitHub Pages in repo settings
4. Use URLs like:
   • Privacy: https://yourusername.github.io/whoop-oauth/privacy.html
   • Redirect: https://yourusername.github.io/whoop-oauth/redirect.html

Option B - Use your own domain:

• Host the HTML files on your existing website

Option C - Local testing only:

• Privacy: http://localhost/privacy.html (Whoop may not accept this)
• Redirect: http://localhost:8080/callback

Step 2: Complete OAuth Flow

1. Create whoop-config.json with your app credentials:

   {
     "client_id": "your-client-id-here",
     "client_secret": "your-client-secret-here",
     "redirect_uri": "https://yourusername.github.io/whoop-oauth/redirect.html"
   }
   

2. Generate authorization URL and authorize:

   python3 scripts/whoop_oauth.py --config whoop-config.json
   

3. Click the authorization URL, log in to Whoop, and authorize

4. Copy the authorization code from the redirect page

5. Exchange code for access token:

   python3 scripts/whoop_oauth.py --config whoop-config.json exchange <CODE>
   

6. Token is automatically saved to ~/.whoop_token

Step 3: Test Connection

python3 scripts/whoop_client.py --action profile

You should see your Whoop profile information!

Common Commands

Today's summary (recovery + sleep + strain):

python3 scripts/whoop_client.py --action today

Specific metrics:

# Recovery data (last 7 days)
python3 scripts/whoop_client.py --action recovery --days 7

# Sleep data
python3 scripts/whoop_client.py --action sleep --days 7

# Cycle data (strain, HRV, calories)
python3 scripts/whoop_client.py --action cycle --days 7

# Workout history
python3 scripts/whoop_client.py --action workout --days 10

Get raw JSON (for parsing/analysis):

python3 scripts/whoop_client.py --action today --json

Analysis Workflows

Morning Briefing

1. Fetch today's data:

   python3 scripts/whoop_client.py --action today --json
   

2. Analyze and provide insights:

   • Recovery score: Green (67-100%), Yellow (34-66%), Red (0-33%)
   • HRV: Compare to user's baseline (track trends, not absolute values)
   • Sleep: Check duration, quality, debt/credit
   • Recommendations: Based on recovery, suggest high/moderate/low strain day

Example briefing:

"🔋 Recovery: 85% (Green) - Your body is well-recovered!

📊 HRV: 68ms (up 8% from baseline) ❤️ RHR: 52 bpm (stable)

😴 Sleep: 8.2 hours, 92% performance

💪 Ready for a high-strain day. Go crush that workout!"

Weekly Analysis

1. Fetch week of data:

   python3 scripts/whoop_client.py --action recovery --days 7 --json
   python3 scripts/whoop_client.py --action sleep --days 7 --json
   python3 scripts/whoop_client.py --action cycle --days 7 --json
   

2. Identify trends:

   • HRV trend (increasing/decreasing)
   • Sleep consistency
   • Strain vs recovery balance
   • Patterns (e.g., low recovery after high strain days)

3. Provide recommendations:

   • Adjust training load
   • Improve sleep habits
   • Plan recovery days

Real-time Alerts

Monitor for warning signs:

• HRV drops >20% from baseline → Consider rest day
• Recovery <33% for 2+ consecutive days → Prioritize recovery
• Sleep performance <50% for 3+ days → Focus on sleep
• High strain (>17) with low recovery (<40%) → Risk of overtraining

Data Interpretation Guide

For detailed metric interpretation and optimal ranges, see references/whoop-api.md.

Key principles:

• Track trends, not absolute values - HRV/RHR baselines vary by individual
• Match strain to recovery - High recovery = can handle high strain
• Consistency matters - Regular sleep schedule improves recovery
• Listen to your body - Metrics are guides, not rules

Troubleshooting

Setup Issues

"Privacy Policy URL must be HTTPS":

• Whoop requires HTTPS URLs (not HTTP)
• Use GitHub Pages, Netlify, or your own HTTPS domain
• Local URLs (localhost) won't work for production apps

"Redirect URI mismatch":

• The redirect URI must match EXACTLY what you configured in Whoop
• Check for trailing slashes, http vs https, etc.
• Example: https://example.com/redirect.html ≠ https://example.com/redirect.html/

OAuth code expired:

• Authorization codes expire quickly (usually within 10 minutes)
• Generate a new auth URL and try again immediately

API Issues

401 Unauthorized:

• Token expired → Re-run OAuth flow to get a new token
• Invalid token → Check ~/.whoop_token file exists and contains valid token
• Wrong scopes → Make sure you authorized all required scopes

404 Not Found (for sleep/cycle endpoints):

• Some endpoints may not be available depending on API version
• Check Whoop developer docs for current endpoint structure
• Try fetching recovery data which includes sleep-related metrics

No data returned:

• Whoop needs to be synced recently (open Whoop app to sync)
• Check date range (data only available for dates when you wore Whoop)
• New users may have limited historical data

Rate limit errors:

• Default limits: 10,000/day, 100/minute
• Spread out requests if hitting limits
• Use pagination (next_token) for large data fetches

Data Issues

Missing metrics:

• Some metrics require Whoop 4.0 (older devices have limited data)
• Sleep data delayed ~1-2 hours after waking (processing time)
• Recovery score requires previous night's sleep to be processed

Unexpected values:

• HRV and RHR vary by individual - track trends, not absolute values
• Recovery score can be affected by alcohol, illness, stress
• Strain accumulates throughout the day (starts low in morning)

Getting Help

1. Check Whoop Developer Docs: https://developer.whoop.com/
2. Review your app settings: https://app.whoop.com/settings/developer
3. Test with Whoop's API explorer (if available)
4. Verify your token with --action profile (simplest endpoint)