Whoop API: Recovery, Strain and Sleep Data for Developers

Key Takeaways

• The Whoop API provides Recovery Score, Strain Score, Sleep Performance, HRV, resting heart rate, respiratory rate and workout data through a cycle-based data model
• Access tokens must be refreshed using rotating refresh tokens: every exchange returns a new refresh token that replaces the previous one
• Whoop data is organized around three cycle types: sleep cycles, recovery cycles and strain cycles, each with its own endpoint and timing
• Recovery data is only available after a sleep cycle completes, which means it cannot be fetched in real time during the day
• Open Wearables handles OAuth, rotating token management and data normalization alongside eight other providers

Introduction

Whoop built its product around a single idea: give athletes a daily answer to the question of whether their body is ready to perform. The Recovery Score, Strain Score and Sleep Performance metrics are the output of continuous biometric monitoring throughout the day and night. For developers building recovery coaching apps, wellness platforms or sports performance tools, Whoop's API provides access to some of the most actionable recovery-oriented data available from a consumer wearable.

But Whoop's data model is different from most wearable APIs in ways that matter for how you architect your integration. Data is organized around cycles, not timestamps. Recovery is a consequence of sleep, not a standalone metric. Strain accumulates across a day rather than being a fixed measurement. Understanding how Whoop thinks about these concepts is a prerequisite to building something useful with the data.

This guide covers what the Whoop API exposes, how the cycle-based model works in practice, what authentication requires, and how the data maps to real product use cases.

What the Whoop API Exposes

Whoop's data model has three primary object types: sleep cycles, recovery cycles and strain cycles. Each maps to a dedicated set of endpoints.

Sleep cycles contain everything recorded during a sleep period: total time in bed, total sleep duration, sleep efficiency (time asleep divided by time in bed), sleep latency (how long it took to fall asleep), sleep staging broken into light, deep and REM percentages, disturbances, respiratory rate during sleep, and the Sleep Performance Score which aggregates these signals into a single 0-100 number. Sleep Performance reflects how well the user slept relative to their individual baseline, not an absolute standard.

Recovery cycles are generated after each sleep cycle ends and the user wakes up. The Recovery Score (0-100) is Whoop's flagship metric: a daily readiness indicator that aggregates heart rate variability, resting heart rate and sleep quality. Whoop color-codes recovery into three zones: green (67-100, ready to perform), yellow (34-66, moderate readiness) and red (0-33, prioritize rest). The underlying biometrics are also available individually: HRV in milliseconds (RMSSD methodology), resting heart rate in beats per minute, respiratory rate, skin temperature deviation on Whoop 4.0+, and SpO2 on compatible hardware.

Strain cycles track daily cardiovascular load. Day Strain is a dimensionless value from 0 to 21 that represents cumulative cardiovascular load. Whoop also tracks individual workouts within the strain cycle, each with its own sport type, duration, heart rate during the session and workout strain score.

What Whoop does not provide: GPS data (Whoop has no GPS), step counts, blood glucose, ECG or any metric requiring optical blood flow measurement beyond heart rate and SpO2.

The Cycle-Based Model in Practice

The most important thing to understand about Whoop data is its temporal structure. A recovery cycle does not exist until the preceding sleep cycle ends. If you query the recovery endpoint at 7 AM before a user has woken up and their sleep cycle has closed, you will get no data for that day. Recovery is a morning metric, available after wake, not a continuous stream.

This has direct implications for your data pipeline. You cannot build a real-time recovery dashboard. The right architecture is a daily morning sync, triggered either on a schedule or by a webhook event when new recovery data becomes available. Many teams schedule this sync to run between 6 and 10 AM in the user's local time zone, after the typical wake window.

Day Strain is the inverse: it accumulates throughout the day and is a running total. If you fetch strain at noon, you get the strain accumulated to that point, not the final daily value. Final strain is available after midnight when the strain cycle closes. If your product shows a day's training load, decide whether to show live intraday strain or closed daily totals, and make that distinction clear to users.

Authentication and Token Management

Whoop uses OAuth 2.0 with the authorization code flow. The key operational detail that differentiates Whoop from most providers is rotating refresh tokens. Every time you exchange a refresh token for a new access token, Whoop returns a new refresh token as well. The previous refresh token is immediately invalidated.

This means your token storage layer needs to handle concurrent refresh attempts carefully. If two background jobs for the same user both detect an expired access token and both attempt to refresh simultaneously, one will succeed and one will receive a 401 because the refresh token it used has already been rotated by the first job. The second job now has an invalid refresh token in its hand and no way to recover without user re-authentication.

The solution is atomic token refresh with distributed locking: acquire a per-user lock before attempting a refresh, check whether the token was already refreshed by another process while waiting for the lock, and only refresh if the stored token still matches what you started with. This is a pattern you need with any rotating-token provider.

The offline scope is required to receive a refresh token at all. Without it, users need to re-authenticate every time the access token expires.

Building With Whoop Data

The practical value of Whoop data in a product context comes from treating the signals as a system rather than individually. Recovery Score alone is useful as a daily headline, but its explanatory power comes from the contributing signals.

A user with a Recovery Score of 42 (yellow zone) wants to know why. If their HRV is 14% below their 30-day baseline but their sleep score was 85, the culprit is cardiovascular stress, not poor sleep. If their sleep score was 58 but HRV was normal, the story is different: the body is physically ready but sleep quality dragged the composite score down. Surfacing these contributing factor breakdowns in your product gives users actionable context rather than just a number to react to.

For coaching applications, the 30-day rolling HRV baseline is more useful than any single HRV reading. Single-day HRV values fluctuate due to alcohol, travel, illness, stress and countless other factors. The trend line and deviation from baseline reveal the underlying fitness trajectory. A user whose HRV baseline has increased 15% over six weeks is adapting positively to training load. A user whose baseline has declined three weeks running while strain remains high is accumulating fatigue.

Open Wearables and Whoop

Open Wearables integrates with Whoop's API and handles OAuth, rotating refresh token management and cycle-based data normalization. Recovery, sleep and workout data is available through a consistent schema shared with Garmin, Oura and other supported providers.

For apps serving users who might have Whoop or Oura or both, Open Wearables normalizes the conceptually similar but technically different recovery scoring models into a unified daily health summary. Your product code works with one schema regardless of which device a user has connected.

Self-hosted, MIT licensed, $0 per user. Deploy via Docker Compose or Railway.

FAQ

Does the Whoop API provide real-time data?

No. Recovery data is generated after a sleep cycle completes. Strain accumulates throughout the day but the daily total is only final after midnight. Whoop is a daily-cadence data source, not a real-time stream.

What Whoop hardware does the API support?

Whoop 4.0 and later. Skin temperature deviation and SpO2 are only available on 4.0+. Older Whoop devices have limited or no API access.

Is the Whoop Recovery Score algorithm public?

No. The Recovery Score methodology is proprietary. You receive the score and the underlying biometrics (HRV, RHR, sleep quality) but not the weighting formula. Open Wearables computes an open, auditable recovery score from the same biometric inputs.

How do I handle the rotating refresh token correctly?

Always store the new refresh token returned from every token exchange, even successful ones that were only refreshing a still-valid access token. Use distributed locking or database-level concurrency controls to prevent simultaneous refresh attempts for the same user.

How long does it take to set up Open Wearables with Whoop?

Deploy takes under an hour with Docker. Whoop OAuth configuration requires registering your app at the Whoop developer portal and adding credentials to the Open Wearables config. First data sync completes within minutes of a user connecting.

Whoop Integration

View the full Whoop integration documentation on Open Wearables.

See Related Articles

Building a Health App With Whoop API Data

Oura API: Accessing Ring Data, Sleep, HRV and Readiness

Strava API Developer Guide: Activities, Heart Rate and GPS Data