WHOOP API

Retrieve and analyze fitness data from WHOOP wearables via the official REST API.

Usage Snippet

bash

# Install (if using Clawdhub)
clawdhub install whoop-tracker

# From the skill root:
python3 scripts/get_recovery.py --today
python3 scripts/get_sleep.py --last
python3 scripts/get_workouts.py --days 7
python3 scripts/get_profile.py

Prerequisites

•Python 3.7+
•requests library: pip3 install requests
(or run bash scripts/install.sh)

Quick Start

1. Register Application

•Go to https://developer.whoop.com
•Create a new app and note your client_id and client_secret
•Set redirect URI (e.g., http://localhost:8080/callback)

2. Save Credentials

bash

mkdir -p ~/.whoop
cat > ~/.whoop/credentials.json <<EOF
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
EOF
chmod 600 ~/.whoop/credentials.json

3. Authorize (see references/oauth.md for full guide)

•Open the authorization URL in browser
•User grants permissions → redirected with code
•Exchange code for tokens via WhoopClient.authenticate(code, redirect_uri)

4. Fetch Data

All scripts are run from the skill root directory:

bash

# Today's recovery
python3 scripts/get_recovery.py --today

# Last night's sleep
python3 scripts/get_sleep.py --last

# Recent workouts
python3 scripts/get_workouts.py --days 7

# User profile
python3 scripts/get_profile.py

Core Data Types

Recovery

•Recovery Score (0-100): Readiness for strain
•HRV (RMSSD): Heart rate variability in milliseconds
•Resting Heart Rate: Morning baseline HR
•SPO2: Blood oxygen percentage
•Skin Temperature: Deviation from baseline in °C

Sleep

•Performance %: How well you slept vs. your sleep need
•Duration: Total time in bed and per stage (REM, SWS, light, awake)
•Efficiency %: Time asleep / time in bed
•Consistency %: How consistent your sleep schedule is
•Respiratory Rate: Breaths per minute
•Sleep Needed/Debt: Baseline need and accumulated debt

Cycle (Daily Strain)

•Strain Score: Cardiovascular load (0-21 scale)
•Kilojoules: Energy expenditure
•Average/Max Heart Rate: Daily HR metrics

Workout

•Strain: Activity-specific strain score
•Sport: Activity type (running, cycling, etc.)
•Heart Rate Zones: Time spent in each of 6 zones
•Distance/Altitude: GPS metrics (if available)

API Endpoints

Base URL: https://api.prod.whoop.com

See references/api-reference.md for full endpoint documentation with response schemas.

User Profile:

•GET /v1/user/profile/basic — Name, email
•GET /v1/user/body_measurement — Height, weight, max HR

Recovery:

•GET /v1/recovery — All recovery data (paginated)
•GET /v1/cycle/{cycleId}/recovery — Recovery for specific cycle

Sleep:

•GET /v1/sleep — All sleep records (paginated)
•GET /v1/sleep/{sleepId} — Specific sleep by ID
•GET /v1/cycle/{cycleId}/sleep — Sleep for specific cycle

Cycle:

•GET /v1/cycle — All physiological cycles (paginated)
•GET /v1/cycle/{cycleId} — Specific cycle by ID

Workout:

•GET /v1/workout — All workouts (paginated)
•GET /v1/workout/{workoutId} — Specific workout by ID

All collection endpoints support start, end (ISO 8601), limit (max 25), and nextToken (pagination cursor).

Required OAuth Scopes

•read:profile — User name and email
•read:body_measurement — Height, weight, max HR
•read:recovery — Recovery scores and HRV
•read:sleep — Sleep metrics and stages
•read:cycles — Daily strain data
•read:workout — Activity and workout data

Scripts

`scripts/whoop_client.py`

Core API client. Features:

•OAuth token storage and auto-refresh
•Token expiry tracking (proactive refresh)
•Rate limit handling (429 with retry)
•Automatic pagination iterators (iter_recovery, iter_sleep, iter_cycles, iter_workouts)

`scripts/get_recovery.py`

bash

python3 scripts/get_recovery.py --today              # Today's recovery
python3 scripts/get_recovery.py --days 7             # Past week
python3 scripts/get_recovery.py --start 2026-01-20   # From date
python3 scripts/get_recovery.py --json               # Raw JSON output

`scripts/get_sleep.py`

bash

python3 scripts/get_sleep.py --last       # Last night
python3 scripts/get_sleep.py --days 7     # Past week
python3 scripts/get_sleep.py --json       # Raw JSON output

`scripts/get_workouts.py`

bash

python3 scripts/get_workouts.py --days 7             # Past week
python3 scripts/get_workouts.py --sport running       # Filter by sport
python3 scripts/get_workouts.py --json                # Raw JSON output

`scripts/get_profile.py`

bash

python3 scripts/get_profile.py            # Profile + body measurements
python3 scripts/get_profile.py --json     # Raw JSON output

`scripts/install.sh`

bash

bash scripts/install.sh                   # Install pip dependencies + setup guide

Troubleshooting

"ModuleNotFoundError: No module named 'requests'"

Install dependencies: pip3 install requests or bash scripts/install.sh

"Credentials not found at ~/.whoop/credentials.json"

Create the file with your OAuth client_id and client_secret (see Quick Start step 2).

"Not authenticated"

Complete the OAuth authorization flow (see references/oauth.md).

"401 Unauthorized" after token refresh fails

Your refresh token has expired. Re-authorize from the authorization URL.

"429 Too Many Requests"

Rate limit hit. The client automatically retries after the Retry-After period.

Empty results

Check your date range — use --days 7 or wider range. Ensure your OAuth scopes include the data type you're requesting.

References

•references/oauth.md — OAuth setup, token management, authorization flow
•references/api-reference.md — Complete API endpoint documentation with response schemas