WHOOP API

Download OpenAPI specification:Download

Authentication

OAuth

Security Scheme Type OAuth2

authorizationCode OAuth Flow

Authorization URL: https://api.prod.whoop.com/oauth/oauth2/auth

Token URL: 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

Security Scheme Type	OAuth2
clientCredentials OAuth Flow	Token URL: https://api.prod.whoop.com/developer/v2/partner/token Scopes: `whoop-partner/token` - Read service requests and upload results.

Activity ID Mapping

Utility endpoints for activity ID mapping

Get V2 UUID for V1 Activity ID

Lookup the V2 UUID for a given V1 activity ID

path Parameters

activityV1Id

required

integer <int64>

Example: 12345678

V1 Activity ID

Responses

Response samples

200

Content type

application/json

{"v2_activity_id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8"
}

Partner

Endpoints for trusted WHOOP partner operations

Generate test data for partner development

Generates test user and lab requisition data for partner integration testing. This endpoint is only available in non-production environments

Authorizations:

Trusted Partner

Responses

Get a lab requisition by ID

Retrieves a lab requisition with its associated service requests by its unique identifier. The requesting partner must be an owner of the lab requisition.

Authorizations:

Trusted Partner

path Parameters

id

required

string <uuid>

Unique identifier of the lab requisition

Responses

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"service_requests": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "string",
"intent": "string",
"code": "string",
"task_business_status": "string",
"task_description": "string"
}
],
"patient": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"appointments": [{"service_request_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"start_time": "2019-08-24T14:15:22Z",
"slot_id": "string",
"collection_address": {"building": "string",
"area": "string",
"emirate": "string",
"landmark": "string",
"flat_no": "string"
}
}
]
}

Get a service request by ID

Retrieves a service request by its unique identifier. The requesting partner must be an owner of the service request.

Authorizations:

Trusted Partner

path Parameters

id

required

string <uuid>

Unique identifier of the service request

Responses

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "string",
"intent": "string",
"code": "string",
"task_business_status": "string",
"task_description": "string"
}

Request a partner client token

Exchanges partner client credentials for an access token.

Request Body schema: application/json

client_id required	string client id for this partner
client_secret required	string
scope	string scope for this token request
grant_type	string grant type for this token request

Responses

Request samples

Payload

Content type

application/json

{"client_id": "string",
"client_secret": "string",
"scope": "string",
"grant_type": "string"
}

Response samples

200

Content type

application/json

{"access_token": "string",
"expires_in": 0,
"token_type": "string"
}

Update lab requisition service request statuses

Updates the task business status on all service requests belonging to the requisition. The requesting partner must be an owner.

Authorizations:

Trusted Partner

path Parameters

id

required

string <uuid>

Unique identifier of the lab requisition

Request Body schema: application/json

task_business_status	string Task business status for workflow tracking (e.g., 'Specimen collected', 'Results pending')
reason	string Optional reason for the task business status change

Responses

Request samples

Payload

Content type

application/json

{"task_business_status": "string",
"reason": "string"
}

Update service request status

Updates the business status of a service request task. The requesting partner must be an owner of the service request.

Authorizations:

Trusted Partner

path Parameters

id

required

string <uuid>

Unique identifier of the service request

Request Body schema: application/json

task_business_status	string Task business status for workflow tracking (e.g., 'Specimen collected', 'Results pending')
reason	string Optional reason for the task business status change

Responses

Request samples

Payload

Content type

application/json

{"task_business_status": "string",
"reason": "string"
}

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "string",
"intent": "string",
"code": "string",
"task_business_status": "string",
"task_description": "string"
}

Create diagnostic report results for a service request

Creates a diagnostic report with results for a service request. The requesting partner must be an owner of the service request.

Authorizations:

Trusted Partner

path Parameters

id

required

string <uuid>

Unique identifier of the service request

Request Body schema: application/json

status	string the status of the diagnostic report
	Array of objects (CreateObservationRequest) [ items ] optional list of observations to attach to the diagnostic report

Responses

Request samples

Payload

Content type

application/json

{"status": "string",
"observations": [{"value_numeric": 0,
"value_text": "string",
"unit": "string",
"status": "string",
"code": "string"
}
]
}

User

Endpoints for retrieving user profile and measurement data.

Get User Body Measurements

Retrieves the body measurements (height, weight, max heart rate) for the authenticated user.

Authorizations:

OAuth (

read:body_measurement

)

Responses

Response samples

200

Content type

application/json

{"height_meter": 1.8288,
"weight_kilogram": 90.7185,
"max_heart_rate": 200
}

Get Basic User Profile

Retrieves the basic profile information (name, email) for the authenticated user.

Authorizations:

OAuth (

read:profile

)

Responses

Response samples

200

Content type

application/json

{"user_id": 10129,
"email": "jsmith123@whoop.com",
"first_name": "John",
"last_name": "Smith"
}

revokeUserOAuthAccess

Revoke the access token granted by the user. If the associated OAuth client is configured to receive webhooks, it will no longer receive them for this user.

Authorizations:

OAuth

Responses

Cycle

getCycleById

Get the cycle for the specified ID

Authorizations:

OAuth (

read:cycles

)

path Parameters

cycleId

required

integer <int64>

ID of the cycle to retrieve

Responses

Response samples

200

Content type

application/json

{"id": 93845,
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"score_state": "SCORED",
"score": {"strain": 5.2951527,
"kilojoule": 8288.297,
"average_heart_rate": 68,
"max_heart_rate": 141
}
}

getCycleCollection

Get all physiological cycles for a user, paginated. Results are sorted by start time in descending order.

Authorizations:

OAuth (

read:cycles

)

query Parameters

limit	integer <int32> <= 25 Default: 10 Limit on the number of cycles returned
start	string <date-time> Return cycles that occurred after or during (inclusive) this time. If not specified, the response will not filter cycles by a minimum time.
end	string <date-time> Return cycles that intersect this time or ended before (exclusive) this time. If not specified, `end` will be set to `now`.
nextToken	string Optional next token from the previous response to get the next page. If not provided, the first page in the collection is returned

Responses

Response samples

200

Content type

application/json

{"records": [{"id": 93845,
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"score_state": "SCORED",
"score": {"strain": 5.2951527,
"kilojoule": 8288.297,
"average_heart_rate": 68,
"max_heart_rate": 141
}
}
],
"next_token": "MTIzOjEyMzEyMw"
}

getSleepForCycle

Get the sleep for the specified cycle ID

path Parameters

cycleId

required

integer <int64>

ID of the cycle to retrieve sleep for

Responses

Response samples

200

Content type

application/json

{"id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8",
"cycle_id": 93845,
"v1_id": 93845,
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"nap": false,
"score_state": "SCORED",
"score": {"stage_summary": {"total_in_bed_time_milli": 30272735,
"total_awake_time_milli": 1403507,
"total_no_data_time_milli": 0,
"total_light_sleep_time_milli": 14905851,
"total_slow_wave_sleep_time_milli": 6630370,
"total_rem_sleep_time_milli": 5879573,
"sleep_cycle_count": 3,
"disturbance_count": 12
},
"sleep_needed": {"baseline_milli": 27395716,
"need_from_sleep_debt_milli": 352230,
"need_from_recent_strain_milli": 208595,
"need_from_recent_nap_milli": -12312
},
"respiratory_rate": 16.11328125,
"sleep_performance_percentage": 98,
"sleep_consistency_percentage": 90,
"sleep_efficiency_percentage": 91.69533848
}
}

Recovery

getRecoveryCollection

Get all recoveries for a user, paginated. Results are sorted by start time of the related sleep in descending order.

Authorizations:

OAuth (

read:recovery

)

query Parameters

limit	integer <int32> <= 25 Default: 10 Limit on the number of recoveries returned
start	string <date-time> Return recoveries that occurred after or during (inclusive) this time. If not specified, the response will not filter recoveries by a minimum time.
end	string <date-time> Return recoveries that intersect this time or ended before (exclusive) this time. If not specified, `end` will be set to `now`.
nextToken	string Optional next token from the previous response to get the next page. If not provided, the first page in the collection is returned

Responses

Response samples

200

Content type

application/json

{"records": [{"cycle_id": 93845,
"sleep_id": "123e4567-e89b-12d3-a456-426614174000",
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"score_state": "SCORED",
"score": {"user_calibrating": false,
"recovery_score": 44,
"resting_heart_rate": 64,
"hrv_rmssd_milli": 31.813562,
"spo2_percentage": 95.6875,
"skin_temp_celsius": 33.7
}
}
],
"next_token": "MTIzOjEyMzEyMw"
}

getRecoveryForCycle

Get the recovery for a cycle

Authorizations:

OAuth (

read:recovery

)

path Parameters

cycleId

required

integer <int64>

ID of the cycle to retrieve

Responses

Response samples

200

Content type

application/json

{"cycle_id": 93845,
"sleep_id": "123e4567-e89b-12d3-a456-426614174000",
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"score_state": "SCORED",
"score": {"user_calibrating": false,
"recovery_score": 44,
"resting_heart_rate": 64,
"hrv_rmssd_milli": 31.813562,
"spo2_percentage": 95.6875,
"skin_temp_celsius": 33.7
}
}

Sleep

getSleepById

Get the sleep for the specified ID

Authorizations:

OAuth (

read:sleep

)

path Parameters

sleepId

required

string <uuid>

ID of the sleep to retrieve

Responses

Response samples

200

Content type

application/json

{"id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8",
"cycle_id": 93845,
"v1_id": 93845,
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"nap": false,
"score_state": "SCORED",
"score": {"stage_summary": {"total_in_bed_time_milli": 30272735,
"total_awake_time_milli": 1403507,
"total_no_data_time_milli": 0,
"total_light_sleep_time_milli": 14905851,
"total_slow_wave_sleep_time_milli": 6630370,
"total_rem_sleep_time_milli": 5879573,
"sleep_cycle_count": 3,
"disturbance_count": 12
},
"sleep_needed": {"baseline_milli": 27395716,
"need_from_sleep_debt_milli": 352230,
"need_from_recent_strain_milli": 208595,
"need_from_recent_nap_milli": -12312
},
"respiratory_rate": 16.11328125,
"sleep_performance_percentage": 98,
"sleep_consistency_percentage": 90,
"sleep_efficiency_percentage": 91.69533848
}
}

getSleepCollection

Get all sleeps for a user, paginated. Results are sorted by start time in descending order.

Authorizations:

OAuth (

read:sleep

)

query Parameters

limit	integer <int32> <= 25 Default: 10 Limit on the number of sleeps returned
start	string <date-time> Return sleeps that occurred after or during (inclusive) this time. If not specified, the response will not filter sleeps by a minimum time.
end	string <date-time> Return sleeps that intersect this time or ended before (exclusive) this time. If not specified, `end` will be set to `now`.
nextToken	string Optional next token from the previous response to get the next page. If not provided, the first page in the collection is returned

Responses

Response samples

200

Content type

application/json

{"records": [{"id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8",
"cycle_id": 93845,
"v1_id": 93845,
"user_id": 10129,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"nap": false,
"score_state": "SCORED",
"score": {"stage_summary": {"total_in_bed_time_milli": 30272735,
"total_awake_time_milli": 1403507,
"total_no_data_time_milli": 0,
"total_light_sleep_time_milli": 14905851,
"total_slow_wave_sleep_time_milli": 6630370,
"total_rem_sleep_time_milli": 5879573,
"sleep_cycle_count": 3,
"disturbance_count": 12
},
"sleep_needed": {"baseline_milli": 27395716,
"need_from_sleep_debt_milli": 352230,
"need_from_recent_strain_milli": 208595,
"need_from_recent_nap_milli": -12312
},
"respiratory_rate": 16.11328125,
"sleep_performance_percentage": 98,
"sleep_consistency_percentage": 90,
"sleep_efficiency_percentage": 91.69533848
}
}
],
"next_token": "MTIzOjEyMzEyMw"
}

getSleepStream

Get the raw signal stream for the specified sleep ID.

path Parameters

sleepId

required

string <uuid>

ID of the sleep to retrieve stream data for

query Parameters

types

Array of strings

Items Enum: "hr" "skin_temp" "board_temp" "battery_temp" "sleep_classification" "charging_status"

Signal types to include in the stream response

Responses

Response samples

200

Content type

application/json

{"stream": [{"timestamp": "2019-08-24T14:15:22Z",
"hr": 0,
"skin_temp": 0,
"board_temp": 0,
"battery_temp": 0,
"is_sleeping": true,
"is_charging": true
}
],
"algorithm_version": "string"
}

Workout

getWorkoutById

Get the workout for the specified ID

Authorizations:

OAuth (

read:workout

)

path Parameters

workoutId

required

string <uuid>

ID of the workout to retrieve

Responses

Response samples

200

Content type

application/json

{"id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8",
"v1_id": 1043,
"user_id": 9012,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"sport_name": "running",
"score_state": "SCORED",
"score": {"strain": 8.2463,
"average_heart_rate": 123,
"max_heart_rate": 146,
"kilojoule": 1569.34033203125,
"percent_recorded": 100,
"distance_meter": 1772.77035916,
"altitude_gain_meter": 46.64384460449,
"altitude_change_meter": -0.781372010707855,
"zone_durations": {"zone_zero_milli": 300000,
"zone_one_milli": 600000,
"zone_two_milli": 900000,
"zone_three_milli": 900000,
"zone_four_milli": 600000,
"zone_five_milli": 300000
}
},
"sport_id": 1
}

getWorkoutCollection

Get all workouts for a user, paginated. Results are sorted by start time in descending order.

Authorizations:

OAuth (

read:workout

)

query Parameters

limit	integer <int32> <= 25 Default: 10 Limit on the number of workouts returned
start	string <date-time> Return workouts that occurred after or during (inclusive) this time. If not specified, the response will not filter workouts by a minimum time.
end	string <date-time> Return workouts that intersect this time or ended before (exclusive) this time. If not specified, `end` will be set to `now`.
nextToken	string Optional next token from the previous response to get the next page. If not provided, the first page in the collection is returned

Responses

Response samples

200

Content type

application/json

{"records": [{"id": "ecfc6a15-4661-442f-a9a4-f160dd7afae8",
"v1_id": 1043,
"user_id": 9012,
"created_at": "2022-04-24T11:25:44.774Z",
"updated_at": "2022-04-24T14:25:44.774Z",
"start": "2022-04-24T02:25:44.774Z",
"end": "2022-04-24T10:25:44.774Z",
"timezone_offset": "-05:00",
"sport_name": "running",
"score_state": "SCORED",
"score": {"strain": 8.2463,
"average_heart_rate": 123,
"max_heart_rate": 146,
"kilojoule": 1569.34033203125,
"percent_recorded": 100,
"distance_meter": 1772.77035916,
"altitude_gain_meter": 46.64384460449,
"altitude_change_meter": -0.781372010707855,
"zone_durations": {"zone_zero_milli": 300000,
"zone_one_milli": 600000,
"zone_two_milli": 900000,
"zone_three_milli": 900000,
"zone_four_milli": 600000,
"zone_five_milli": 300000
}
},
"sport_id": 1
}
],
"next_token": "MTIzOjEyMzEyMw"
}