# WHOOP
## Complete Data Collection, API & Integration Reference

**Peptide Resource Hub | Optimize Inner Circle | Developer Reference | WHOOP 4.0 + 5.0 + MG**

---

## Document Scope

This reference covers everything needed to integrate WHOOP into the Peptide Resource Hub app: hardware sensor capabilities (3.0, 4.0, 5.0, MG), WHOOP API v2 endpoint reference with JSON schemas, OAuth 2.0 and token management, webhook architecture, user-facing export formats, field mapping to the PRH normalized schema, and peptide protocol KPI mapping. It is the WHOOP equivalent of the Apple Watch + Oura Ring combined reference.

---

## PART 1 — WHAT WHOOP IS | Platform Overview

### 1.1 WHOOP Platform Philosophy

WHOOP is a **pure physiological monitoring platform** with a subscription-first model: no screen, no GPS, no notifications. Users pay a membership (device included) — they are buying a coaching subscription. Target users: serious athletes, biohackers, health optimizers (Peptide Resource Hub demographic).

| Dimension | WHOOP |
|-----------|--------|
| Form Factor | Screenless wristband (also WHOOP Body apparel: chest, waist, calf, bicep, bra) |
| Primary Value | Recovery coaching, strain tracking, sleep optimization |
| Business Model | Subscription — One, Peak, or Life tiers. No one-time device purchase. |
| Data Sampling | 100 Hz continuous PPG — higher than Apple Watch or Oura during wear |
| Battery Life | 4.0: 4–5 days \| 5.0 and MG: 14+ days (charges on-wrist) |
| Current Devices | WHOOP 4.0 (legacy), WHOOP 5.0, WHOOP MG (medical-grade, 2025) |
| Pricing (2025) | One: $199/yr \| Peak: $239/yr \| Life (MG): $359/yr |
| Developer API | Free — requires WHOOP device + developer account at developer.whoop.com |

### 1.2 Membership Tiers — Data Availability

| Feature / Metric | WHOOP One | WHOOP Peak | WHOOP Life (MG only) |
|------------------|-----------|------------|----------------------|
| Strain, Recovery, Sleep, HRV, Resting HR, Respiratory Rate, SpO2, Skin Temp, Workout, VO2 Max, Steps, Cycle Insights | Yes | Yes | Yes |
| Health Monitor (live vitals) | No | Yes | Yes |
| Stress Monitor (real-time stress score) | No | Yes | Yes |
| Healthspan / WHOOP Age / Pace of Aging | No | Yes | Yes |
| Heart Screener (ECG, AFib) | No | No | Yes — MG, FDA-cleared |
| Blood Pressure Insights | No | No | Yes — MG only |
| Irregular Heart Rhythm Notifications | No | No | Yes — MG |
| Advanced Skin Temperature Sensor | No | No | Yes — MG |

---

## PART 2 — HARDWARE SENSOR INVENTORY

### 2.1 Sensor Hardware by Generation

| Sensor | 3.0 | 4.0 | 5.0 | MG |
|--------|-----|-----|-----|-----|
| PPG (Heart Rate, 100 Hz) | Yes | Yes | Yes (upgraded) | Same as 5.0 |
| HRV (rmssd) | Yes — nightly | Yes — nightly | Yes — nightly + daytime | Yes |
| SpO2 | No | Yes — nightly | Yes — nightly | Yes — nightly + continuous |
| Skin Temperature | No | Yes — nightly deviation | Yes | Yes — enhanced |
| Respiratory Rate | Yes | Yes | Yes | Yes — improved |
| ECG / AFib | No | No | No | Yes — FDA-cleared |
| Blood Pressure (estimated) | No | No | No | Yes — MG |
| Battery Life | ~5 days | 4–5 days | 14+ days | 14+ days |
| Body Placement (non-wrist) | No | Yes (WHOOP Body) | Yes | Yes |

### 2.2 Key Metric Definitions — WHOOP Terminology

| WHOOP Term | Definition | Range / Unit | Oura / Apple Equivalent |
|------------|------------|--------------|--------------------------|
| **Strain Score** | Cardiovascular load, 0–21 logarithmic scale over a physiological cycle (day) | 0–21 | No direct equivalent — Oura activity score; Apple active calories / exercise min |
| **Recovery Score** | 0–100% composite from HRV, resting HR, sleep performance, respiratory rate | 0–100% | Oura: Readiness Score. Apple: None. |
| **HRV (rmssd)** | Root Mean Square of Successive Differences, nightly during final sleep stages | ms | Oura: rmssd. Apple: SDNN (different — not comparable). |
| **Physiological Cycle** | One “day” from wake to wake (not midnight-to-midnight) | ~24 hrs | Oura: day. Apple: calendar day. |
| **Sleep Performance %** | % of sleep needed that you actually got (WHOOP sleep need algorithm) | 0–100% | Oura: efficiency % (different calc). Apple: none. |
| **Slow Wave Sleep** | WHOOP term for deep sleep (N3/SWS) | ms | Oura: deep_sleep_duration. Apple: AsleepDeep. |
| **Disturbance Count** | Awakenings/movement disruptions during sleep | Integer | Oura: inferred from hypnogram. Apple: awake intervals. |
| **WHOOP Age** | Physiological age from 9 longevity biomarkers (5.0/Peak) | Years | No equivalent in Oura/Apple. |
| **Pace of Aging** | Rate of aging (-1.0x to 3.0x), updated weekly | Scale | No equivalent. |

---

## PART 3 — WHOOP API v2 | Endpoint Reference

### 3.1 API Overview & Authentication

| Parameter | Value |
|-----------|--------|
| Base URL | https://api.prod.whoop.com/developer |
| Auth | OAuth 2.0 — Authorization Code Flow |
| Authorization URL | https://api.prod.whoop.com/oauth/oauth2/auth |
| Token URL | https://api.prod.whoop.com/oauth/oauth2/token |
| Token Revocation | DELETE /v2/user/access |
| Pagination | Cursor-based via nextToken; max 25 records per request |
| Rate Limiting | HTTP 429 — implement Retry-After and exponential backoff |
| OpenAPI | https://api.prod.whoop.com/developer/doc/openapi.json |

### 3.2 OAuth Scopes

| Scope | Data Access |
|-------|-------------|
| read:recovery | Recovery score, HRV rmssd, resting HR, SpO2, skin temp |
| read:cycles | Physiological cycles, Strain score, average/max HR, kilojoules |
| read:sleep | Sleep sessions — stages, performance %, consistency, efficiency, respiratory rate |
| read:workout | Workout sessions — sport type, strain, HR zones, duration, kilojoules |
| read:profile | User name, email |
| read:body_measurement | Height, weight, max heart rate |

### 3.3 Key Endpoints & Response Schemas

**User:** GET /v2/user/profile/basic (user_id, email, first_name, last_name). GET /v2/user/measurement/body (height_meter, weight_kilogram, max_heart_rate).

**Cycles (physiological day = wake to wake):**
- GET /v2/cycle — Params: limit, start, end, nextToken. Response: records[].id (integer), start, end, timezone_offset, score_state (SCORED | PENDING_SCORE | UNSCORABLE), score.strain, score.kilojoule, score.average_heart_rate, score.max_heart_rate; next_token.
- GET /v2/cycle/{cycleId}, GET /v2/cycle/{cycleId}/sleep, GET /v2/cycle/{cycleId}/recovery.

**Recovery (primary PRH KPI source):**
- GET /v2/recovery — Params: limit, start, end, nextToken. Response: records[].cycle_id, sleep_id (UUID), user_id, created_at, updated_at, score_state, score.user_calibrating, score.recovery_score (0–100), score.resting_heart_rate, score.hrv_rmssd_milli, score.spo2_percentage, score.skin_temp_celsius (absolute °C). **Only use when score_state == 'SCORED'.**

**Sleep:**
- GET /v2/activity/sleep, GET /v2/activity/sleep/{sleepId}. Response: id (UUID), cycle_id, start, end, timezone_offset, nap, score.stage_summary (total_in_bed_time_milli, total_awake_time_milli, total_light_sleep_time_milli, total_slow_wave_sleep_time_milli, total_rem_sleep_time_milli, sleep_cycle_count, disturbance_count), score.sleep_needed (baseline_milli, need_from_sleep_debt_milli, etc.), score.respiratory_rate, score.sleep_performance_percentage, score.sleep_efficiency_percentage. **No per-epoch hypnogram in API** — stage totals only.

**Workout:**
- GET /v2/activity/workout, GET /v2/activity/workout/{workoutId}. Response: id (UUID), start, end, sport_id, score.strain, score.average_heart_rate, score.max_heart_rate, score.kilojoule, score.zone_duration (zone_zero_milli through zone_five_milli).

**Sport IDs (examples):** -1 = Activity (generic), 0 = Running, 1 = Cycling, 16 = Weightlifting, 44 = CrossFit, 71 = HIIT, 96 = Rowing, 102 = Swimming, 104 = Yoga, 103 = Sauna, etc.

---

## PART 4 — WEBHOOKS

WHOOP POSTs to your HTTPS endpoint when data is updated. Respond with 2xx within 5 seconds; then fetch full data by id.

| Event Type | Trigger | ID in Payload | Fetch From |
|------------|---------|---------------|------------|
| workout.updated | Workout scored/updated | UUID (v2 workout ID) | GET /v2/activity/workout/{id} |
| sleep.updated | Sleep scored/updated | UUID (v2 sleep ID) | GET /v2/activity/sleep/{id} |
| recovery.updated | Recovery computed after sleep | UUID (v2 sleep ID) | GET /v2/cycle/{cycle_id}/recovery |
| cycle.updated | Cycle updated | Integer cycle ID | GET /v2/cycle/{cycleId} |

**Payload format:** `{ user_id, id (UUID in v2), type (e.g. "sleep.updated"), trace_id }`.

**Signature validation:** Headers X-WHOOP-Signature (SHA256 HMAC hex), X-WHOOP-Signature-Timestamp. Payload = timestamp + rawBody; verify HMAC with your webhook secret. v1 webhooks (integer IDs) removed as of 2025 — use v2 UUIDs only.

---

## PART 5 — USER-FACING EXPORT FORMATS

| Export Method | Format | Access | Contents |
|---------------|--------|--------|----------|
| Health Monitor PDF | PDF | App > Health Monitor > Export (30 or 180 days) | Summary charts — not raw data; for sharing with coaches/physicians |
| Account Data Download | ZIP (JSON) | App > Account > Privacy > Export Data | cycles.json, sleeps.json, recoveries.json, workouts.json, journal_entries.json, profile.json — matches API schema |
| WHOOP Journal CSV | CSV | App > Journal > Export | User-logged tags/behaviors — good for protocol correlation |
| WHOOP API | JSON | REST v2 | Full data, any date range; best path for app. Real-time via webhooks. |
| Apple Health Integration | HealthKit write | WHOOP app > Apple Health | WHOOP writes resting HR, HRV (as SDNN estimate), respiratory rate, sleep, workouts, active calories, SpO2. **Dedupe with WHOOP API** — check sourceName/bundleIdentifier (com.whoop.Whoop). |

---

## PART 6 — FIELD MAPPING TO PRH NORMALIZED SCHEMA

### 6.1 Recovery → health_measurements

| WHOOP Field | PRH Field | Type / Notes |
|-------------|-----------|--------------|
| score.recovery_score | value (metric_type: recovery_score) | INT 0–100 → FLOAT |
| score.resting_heart_rate | value (metric_type: resting_heart_rate) | bpm |
| score.hrv_rmssd_milli | value (metric_type: hrv_rmssd) | FLOAT ms |
| score.spo2_percentage | value (metric_type: spo2) | FLOAT %; null if 3.0 |
| score.skin_temp_celsius | value (metric_type: skin_temp_absolute) | FLOAT °C absolute — compute 30-day baseline yourself for deviation |
| created_at | start_timestamp_utc (proxy) | ISO 8601 UTC → epoch ms |
| score_state | raw_payload | Only ingest if SCORED |
| score.user_calibrating | raw_payload | Flag calibration period (~28 days) |

### 6.2 Sleep → sleep_sessions

| WHOOP Field | PRH Field | Notes |
|-------------|-----------|-------|
| start, end | bedtime_start_utc, wake_time_utc | ISO 8601 UTC → epoch ms |
| total_in_bed_time_milli | total_in_bed_sec | ms / 1000 |
| total_light_sleep_time_milli | core_sleep_sec | WHOOP light = NREM N1+N2 = core |
| total_slow_wave_sleep_time_milli | deep_sleep_sec | SWS = deep |
| total_rem_sleep_time_milli | rem_sleep_sec | |
| total_awake_time_milli | awake_time_sec | |
| sleep_efficiency_percentage | sleep_efficiency_pct | |
| respiratory_rate | avg_respiratory_rate | br/min |
| sleep_cycle_count, disturbance_count | raw_payload | No direct PRH columns |

### 6.3 Cycle → health_measurements (Strain)

| WHOOP Field | PRH (metric_type) | Unit |
|-------------|--------------------|------|
| score.strain | whoop_strain_score | 0–21 float (WHOOP-exclusive) |
| score.kilojoule | whoop_energy_kj (or convert to kcal) | kJ |
| score.average_heart_rate | heart_rate (daily average) | bpm |
| start, end | start_timestamp_utc, end_timestamp_utc | UTC epoch ms |

---

## PART 7 — PEPTIDE PROTOCOL KPI MAPPING | WHOOP-Specific

**WHOOP’s strength for PRH:** Strain-to-Recovery arc. For tissue repair (BPC-157, TB-500), watch Recovery + HRV while maintaining or increasing Strain. For GH secretagogues (CJC-1295/Ipamorelin), watch **slow wave sleep time** and Recovery together.

| Peptide Protocol | Primary WHOOP KPIs | Secondary | Endpoint |
|------------------|---------------------|-----------|----------|
| BPC-157 | Recovery Score, HRV rmssd, Resting HR | Strain tolerance (Strain increase as recovery improves?), sleep performance % | recovery, cycle |
| TB-500 | Average HR during cycle, Max HR during workout, Strain Score | Recovery, kilojoule, zone_duration (Z4–Z5) | cycle, workout |
| CJC-1295 / Ipamorelin | **Slow Wave Sleep (ms)**, Recovery Score, HRV | Sleep performance %, sleep cycle count, respiratory rate | sleep (stage_summary), recovery |
| Sermorelin / Tesamorelin | Slow Wave Sleep, Recovery, cycle avg HR at rest | Strain-to-kilojoule ratio, sleep consistency % | sleep, recovery, cycle |
| PT-141 | HRV, Recovery, sleep performance % | Strain (mood proxy) | recovery, sleep |
| KPV / LL-37 | Resting HR, HRV, skin_temp_celsius | Recovery, disturbance count, respiratory rate | recovery, sleep |
| Epithalon | **Sleep consistency %**, sleep performance %, slow wave sleep | HRV trend, recovery trend | sleep, recovery |
| Selank / Semax | HRV, resting HR, recovery | Disturbance count (fewer = less anxious arousal) | recovery, sleep |
| GLP-1 analogs | Body weight (profile/body_measurement), Strain trajectory, kilojoule | Avg HR at given strain (efficiency), recovery | cycle, workout, body_measurement |
| Dihexa / Semax (nootropic) | Recovery (cognitive fatigue proxy), HRV, sleep performance | Strain (motivation proxy) | recovery, sleep, cycle |

---

## PART 8 — THREE-WAY COMPARISON | WHOOP vs. Oura vs. Apple Watch

| Dimension | WHOOP | Oura Ring | Apple Watch |
|-----------|--------|-----------|-------------|
| HRV Metric | rmssd (nightly) | rmssd (nightly) | SDNN (not comparable to rmssd) |
| Recovery Score | Yes — 0–100% | Yes — Readiness 0–100 | No native |
| Strain / Load Score | Yes — Strain 0–21 | No (activity score different) | Active cal + exercise min |
| Deep Sleep | Yes — slow wave (ms) | Yes — deep_sleep_duration | Yes — AsleepDeep |
| Per-Epoch Hypnogram | No — totals only | Yes — 5-min epoch via API | Yes — per-interval |
| Nightly SpO2 | Yes — 4.0+ | Yes — Gen 3/4 | Yes — Series 6+ (US limits) |
| Skin Temperature | Yes — absolute °C (4.0+) | Yes — deviation from baseline | Yes — deviation (Series 8+) |
| Daytime Stress | Yes — Peak/Life | Yes — Resilience | No (passive only) |
| ECG / AFib | Yes — MG + Life only | No | Yes — Series 4+ |
| Blood Pressure | Yes — MG + Life only | No | No (Series 10 some regions) |
| GPS | No (phone) | No | Yes |
| API Access | Free — OAuth, REST, webhooks | Free — OAuth, REST | HealthKit (iOS app required) |
| PRH Primary Use | Strain/Recovery arc, athletic response | Sleep architecture, temp, readiness | Activity, GPS, ECG, CGM, clinical |

### Integration Priority for PRH

- **TIER 1:** Oura Ring (sleep, readiness, per-epoch), Apple Watch (CGM, ECG, activity).
- **TIER 2:** WHOOP (Strain/Recovery, athlete segment).
- **TIER 3:** Garmin, Terra API (middleware).

---

## PART 9 — APPLE HEALTH PASSTHROUGH | Double-Count Prevention

WHOOP writes to HealthKit when user enables in WHOOP app: resting HR, HRV (as SDNN estimate), respiratory rate, sleep stages, workouts, active calories, SpO2. If your app reads **both** HealthKit and WHOOP API, **deduplicate**: check sourceName / bundleIdentifier (com.whoop.Whoop). Include source in dedup_hash so whoop_api and whoop_via_healthkit produce different hashes and do not double-count.

---

## PART 10 — PRIVACY, COMPLIANCE & DEVELOPER GOTCHAS

- OAuth required; implement DELETE /v2/user/access on disconnect. Store tokens server-side only; never in client.
- **score_state** must be 'SCORED' before using score fields. PENDING_SCORE = null; UNSCORABLE = not worn.
- **user_calibrating** = true for ~28 days; flag these records.
- Pagination: cursor-based nextToken only; next_token null = last page.
- **Cycle timing:** Cycles are wake-to-wake, not midnight-to-midnight. Use cycle **end** for local_date.
- **Naps:** nap: true records are separate; do not merge with nightly sleep.
- **Skin temp:** WHOOP gives absolute °C; Oura gives deviation. Compute 30-day baseline for WHOOP if you need deviation.
- **HRV:** WHOOP and Oura use rmssd; Apple uses SDNN — do not mix in same chart without labeling source.
- v2 uses UUIDs for sleep/workout; v1 used integers. Use /v1/activity-mapping only for migration; new code = v2 UUIDs only.
- Webhooks: HTTPS only; validate HMAC-SHA256 signature.

---

*WHOOP Complete Data Collection, API & Integration Reference | Peptide Resource Hub | Optimize Inner Circle | Q1 2026*