openapi: 3.0.1 info: title: WHOOP Activity ID Mapping Sleep API version: 2.0.0 description: The WHOOP API exposes member fitness, strain, recovery, sleep, workout, and body measurement data captured by the WHOOP wrist-worn wearable. OAuth 2.0 protected; v2 endpoints use UUID identifiers and webhook notifications keep integrations current. contact: name: WHOOP Developer Support url: https://developer.whoop.com/docs/developing/support license: name: WHOOP API Terms url: https://www.whoop.com/legal/api-terms/ servers: - url: https://api.prod.whoop.com/developer tags: - name: Sleep paths: /v2/activity/sleep/{sleepId}: get: tags: - Sleep description: Get the sleep for the specified ID operationId: getSleepById parameters: - name: sleepId in: path description: ID of the sleep to retrieve required: true schema: type: string format: uuid responses: '200': description: Successful request content: application/json: schema: $ref: '#/components/schemas/Sleep' '400': description: Client error constructing the request '404': description: No resource found '401': description: Invalid authorization '429': description: Request rejected due to rate limiting '500': description: Server error occurred while making request security: - OAuth: - read:sleep summary: Get Sleep /v2/activity/sleep: get: tags: - Sleep description: Get all sleeps for a user, paginated. Results are sorted by start time in descending order. operationId: getSleepCollection parameters: - name: limit in: query description: Limit on the number of sleeps returned schema: maximum: 25 type: integer format: int32 default: 10 - name: start in: query description: Return sleeps that occurred after or during (inclusive) this time. If not specified, the response will not filter sleeps by a minimum time. schema: type: string format: date-time - name: end in: query description: Return sleeps that intersect this time or ended before (exclusive) this time. If not specified, `end` will be set to `now`. schema: type: string format: date-time - name: nextToken in: query description: Optional next token from the previous response to get the next page. If not provided, the first page in the collection is returned schema: type: string responses: '200': description: Successful request content: application/json: schema: $ref: '#/components/schemas/PaginatedSleepResponse' '400': description: Client error constructing the request '401': description: Invalid authorization '429': description: Request rejected due to rate limiting '500': description: Server error occurred while making request security: - OAuth: - read:sleep summary: List Sleep components: schemas: SleepStageSummary: required: - disturbance_count - sleep_cycle_count - total_awake_time_milli - total_in_bed_time_milli - total_light_sleep_time_milli - total_no_data_time_milli - total_rem_sleep_time_milli - total_slow_wave_sleep_time_milli type: object properties: total_in_bed_time_milli: type: integer description: Total time the user spent in bed, in milliseconds format: int32 example: 30272735 total_awake_time_milli: type: integer description: Total time the user spent awake, in milliseconds format: int32 example: 1403507 total_no_data_time_milli: type: integer description: Total time WHOOP did not receive data from the user during the sleep, in milliseconds format: int32 example: 0 total_light_sleep_time_milli: type: integer description: Total time the user spent in light sleep, in milliseconds format: int32 example: 14905851 total_slow_wave_sleep_time_milli: type: integer description: Total time the user spent in Slow Wave Sleep (SWS), in milliseconds format: int32 example: 6630370 total_rem_sleep_time_milli: type: integer description: Total time the user spent in Rapid Eye Movement (REM) sleep, in milliseconds format: int32 example: 5879573 sleep_cycle_count: type: integer description: Number of sleep cycles during the user's sleep format: int32 example: 3 disturbance_count: type: integer description: Number of times the user was disturbed during sleep format: int32 example: 12 description: Summary of the sleep stages externalDocs: description: Sleep Consistency and Sleep Stages url: https://support.whoop.com/hc/en-us/articles/360019623493-Sleep-Consistency-and-Sleep-Stages PaginatedSleepResponse: type: object properties: records: type: array description: The collection of records in this page. items: $ref: '#/components/schemas/Sleep' next_token: type: string description: A token that can be used on the next request to access the next page of records. If the token is not present, there are no more records in the collection. example: MTIzOjEyMzEyMw Sleep: required: - created_at - cycle_id - end - id - nap - score_state - start - timezone_offset - updated_at - user_id type: object properties: id: type: string description: Unique identifier for the sleep activity format: uuid example: ecfc6a15-4661-442f-a9a4-f160dd7afae8 cycle_id: type: integer description: Unique identifier for the cycle this sleep belongs to format: int64 example: 93845 v1_id: type: integer description: Previous generation identifier for the activity. Will not exist past 09/01/2025 format: int64 example: 93845 user_id: type: integer description: The WHOOP User who performed the sleep activity format: int64 example: 10129 created_at: type: string description: The time the sleep activity was recorded in WHOOP format: date-time example: '2022-04-24T11:25:44.774Z' updated_at: type: string description: The time the sleep activity was last updated in WHOOP format: date-time example: '2022-04-24T14:25:44.774Z' start: type: string description: Start time bound of the sleep format: date-time example: '2022-04-24T02:25:44.774Z' end: type: string description: End time bound of the sleep format: date-time example: '2022-04-24T10:25:44.774Z' timezone_offset: type: string description: The user's timezone offset at the time the sleep was recorded. Follows format for Time Zone Designator (TZD) - '+hh:mm', '-hh:mm', or 'Z'. example: -05:00 externalDocs: description: Learn more about the Time Zone Designator from the W3C Standard url: https://www.w3.org/TR/NOTE-datetime nap: type: boolean description: If true, this sleep activity was a nap for the user example: false score_state: type: string description: '`SCORED` means the sleep activity was scored and the measurement values will be present. `PENDING_SCORE` means WHOOP is currently evaluating the sleep activity. `UNSCORABLE` means this activity could not be scored for some reason - commonly because there is not enough user metric data for the time range.' example: SCORED enum: - SCORED - PENDING_SCORE - UNSCORABLE score: $ref: '#/components/schemas/SleepScore' description: The collection of records in this page. SleepNeeded: required: - baseline_milli - need_from_recent_nap_milli - need_from_recent_strain_milli - need_from_sleep_debt_milli type: object properties: baseline_milli: type: integer description: The amount of sleep a user needed based on historical trends format: int64 example: 27395716 need_from_sleep_debt_milli: type: integer description: The difference between the amount of sleep the user's body required and the amount the user actually got format: int64 example: 352230 externalDocs: description: WHOOP Locker - What is Sleep Debt & How Do You Catch Up on Sleep? url: https://www.whoop.com/thelocker/what-is-sleep-debt-catch-up/ need_from_recent_strain_milli: type: integer description: Additional sleep need accrued based on the user's strain format: int64 example: 208595 need_from_recent_nap_milli: type: integer description: Reduction in sleep need accrued based on the user's recent nap activity (negative value or zero) format: int64 example: -12312 description: Breakdown of the amount of sleep a user needed before the sleep activity. Summing all individual components results in the amount of sleep the user needed prior to this sleep activity SleepScore: required: - sleep_needed - stage_summary type: object properties: stage_summary: $ref: '#/components/schemas/SleepStageSummary' sleep_needed: $ref: '#/components/schemas/SleepNeeded' respiratory_rate: type: number description: The user's respiratory rate during the sleep. format: float example: 16.11328125 sleep_performance_percentage: type: number description: A percentage (0-100%) of the time a user is asleep over the amount of sleep the user needed. May not be reported if WHOOP does not have enough data about a user yet to calculate Sleep Need. format: float example: 98.0 sleep_consistency_percentage: type: number description: Percentage (0-100%) of how similar this sleep and wake times compared to the previous day. May not be reported if WHOOP does not have enough sleep data about a user yet to understand consistency. format: float example: 90.0 externalDocs: description: WHOOP Locker - What is Sleep Consistency? url: https://www.whoop.com/thelocker/new-feature-sleep-consistency-why-we-track-it/ sleep_efficiency_percentage: type: number description: A percentage (0-100%) of the time you spend in bed that you are actually asleep. format: float example: 91.69533848 externalDocs: description: 'WHOOP Locker - Sleep Efficiency: What is It, How Do You Stack Up & How Can You Improve?' url: https://www.whoop.com/thelocker/app-feature-improve-sleep-efficiency/ description: WHOOP's measurements and evaluation of the sleep activity. Only present if the Sleep State is `SCORED` securitySchemes: OAuth: type: oauth2 flows: authorizationCode: authorizationUrl: https://api.prod.whoop.com/oauth/oauth2/auth tokenUrl: https://api.prod.whoop.com/oauth/oauth2/token scopes: read:recovery: Read Recovery data, including score, heart rate variability, and resting heart rate. read:cycles: Read cycles data, including day Strain and average heart rate during a physiological cycle. read:workout: Read workout data, including activity Strain and average heart rate. read:sleep: Read sleep data, including performance % and duration per sleep stage. read:profile: Read profile data, including name and email. read:body_measurement: Read body measurements data, including height, weight, and max heart rate. Trusted Partner: type: oauth2 flows: clientCredentials: tokenUrl: https://api.prod.whoop.com/developer/v2/partner/token scopes: whoop-partner/token: Read service requests and upload results.