WHOOP API

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

Usage Snippet

CODEBLOCK0

Prerequisites

• - Python 3.7+
• INLINECODE0 library: INLINECODE1

(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 INLINECODE4
• Set redirect URI (e.g., http://localhost:8080/callback)

2. Save Credentials

CODEBLOCK1

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 INLINECODE6

4. Fetch Data

All scripts are run from the skill root directory:

CODEBLOCK2

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: INLINECODE7

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

User Profile:

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

Recovery:

• - GET /v1/recovery — All recovery data (paginated)
• INLINECODE11 — Recovery for specific cycle

Sleep:

• - GET /v1/sleep — All sleep records (paginated)
• INLINECODE13 — Specific sleep by ID
• INLINECODE14 — Sleep for specific cycle

Cycle:

• - GET /v1/cycle — All physiological cycles (paginated)
• INLINECODE16 — Specific cycle by ID

Workout:

• - GET /v1/workout — All workouts (paginated)
• INLINECODE18 — 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
• INLINECODE24 — Height, weight, max HR
• INLINECODE25 — Recovery scores and HRV
• INLINECODE26 — Sleep metrics and stages
• INLINECODE27 — Daily strain data
• INLINECODE28 — 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

CODEBLOCK3

scripts/get_sleep.py

CODEBLOCK4

scripts/get_workouts.py

CODEBLOCK5

scripts/get_profile.py

CODEBLOCK6

scripts/install.sh

CODEBLOCK7

Troubleshooting

"ModuleNotFoundError: No module named 'requests'"

Install dependencies: pip3 install requests or INLINECODE40

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

Create the file with your OAuth clientid and clientsecret (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