Skip to main content
API docs by Redocly

ROOK (2.0.1)

Download OpenAPI specification:Download

Intro

ROOK is a set of services that simplifies the collection, processing, and delivering of Users' HealthData from various data sources.

Testing

You can use the following constants to test the API and receive default responses:

  • client_uuid = Your "client_uuid" for testing you can use: 'demoClientUUID'
  • client secret = Your "client secret" for testing you can use: 'demoClientSecret'
  • user_id = Your "user_id" for testing you can use: 'demoUserId'
  • date = Your "date" for testing you can use: '2022-10-28'

ROOK > Connect > User

[User][Data Source][Authorizer]

Retrieves the authorization status for a specific data source linked to a given user. - If the user is not authorized, an authorization URL is provided to start the process. - If the user is already authorized, the response will indicate "authorized": true and no authorization URL will be returned. - The redirect_url parameter can be used to specify where the user should be redirected after completing the authorization.

Authorizations:
basicAuth
path Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

data_source
required
string
Enum: "Garmin" "Oura" "Polar" "Fitbit" "Withings" "Whoop" "Dexcom"

The data source to be authorized. Allowed values: Garmin, Oura, Polar, Fitbit, Withings, Whoop, Dexcom.

query Parameters
redirect_url
string <uri> [ 1 .. 50 ] characters ^https://.+
Example: redirect_url=https://example.com

(Optional): Designates a custom URL to which the user is redirected after a successful authentication or linking process. In its absence, the redirection will be to ROOK's connections page (or the default configured) to continue the post-authentication flow.

Important: The redirect_url provided in the query parameter will be used as the base URL. After calling this endpoint, the API will append client_uuid and user_id as path parameters to the provided URL.

The client must ensure that their system correctly handles this transformation to avoid 404 errors or unexpected behavior.

Final URL format after processing:
{redirect_url}/client_uuid/<client_uuid>/user_id/<user_id>

Responses

Response samples

Content type
application/json
{}

[DEPRECATED] [User][Data Sources][Authorizers] Deprecated

THIS ENDPOINT IS DEPRECATED AND WILL BE REMOVED IN A FUTURE RELEASE.

This endpoint retrieves all enabled data sources for a user, including:

  • Data source name
  • Description
  • Logo
  • Authorization URL (if applicable)
  • User’s current authorization status

Additionally, it provides theme settings for customizing the ROOK connection page.

** RECOMMENDED ALTERNATIVE:**
Instead of using this endpoint, it is recommended to query individual authorizations using:

  • /api/v1/user_id/{user_id}/data_source/{data_source}/authorizer
    This new endpoint provides a more efficient and scalable solution, reducing unnecessary data retrieval.
Authorizations:
basicAuth
path Parameters
client_uuid
required
string <uuid> (schema_client_uuid)
Example: demoClientUUID

A unique identifier for each client, in UUID4 format. Provided by ROOK upon signing service agreements.

user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

query Parameters
redirect_url
string <uri> [ 1 .. 50 ] characters ^https://.+
Example: redirect_url=https://example.com

(Optional): Designates a custom URL to which the user is redirected after a successful authentication or linking process. In its absence, the redirection will be to ROOK's connections page (or the default configured) to continue the post-authentication flow.

Important: The redirect_url provided in the query parameter will be used as the base URL. After calling this endpoint, the API will append client_uuid and user_id as path parameters to the provided URL.

The client must ensure that their system correctly handles this transformation to avoid 404 errors or unexpected behavior.

Final URL format after processing:
{redirect_url}/client_uuid/<client_uuid>/user_id/<user_id>

Responses

Response samples

Content type
application/json
null

[User][Data Sources][Authorized]

Returns the list of data sources that are authorized for the specified user, previously created using the /authorizers endpoint or through the SDKs.

For SDK-based data sources (such as Apple Health and Health Connect), this endpoint will return true if the user was created by SDK with the corresponding updateUserId function, means that the user is linked with ROOK via SDK, but not indicates if the user granted permissions or not.

For API-based data sources (such as Fitbit, Garmin, and Withings), true indicates that the user has authorized ROOK to retrieve data through the respective third-party platform.

Important Notice:
Google Fit support ends on November 4, 2025, and is scheduled for deprecation. Avoid using this source in any new implementation. For more information, visit the Google Fit deprecation notice.

RECOMMENDED ALTERNATIVE:

It is recommended to query status authorized using:

  • /api/v2/user_id/{user_id}/data_sources/authorized

This new endpoint provides a more efficient and scalable solution.

Authorizations:
basicAuth
path Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

Responses

Response samples

Content type
application/json
{
  • "user_id": "demoUserId",
  • "sources": {
    }
}

[User][Data Sources][Authorized][V2]

🟢 Recommended version
Use this version instead of V1 to retrieve status authorized data sources and image corresponding

Returns the list of data sources that are authorized for the specified user, previously created using the /authorizer endpoint or through the SDKs.

Each data source object includes:

  • data_source: Name of the integration (e.g., Garmin, Fitbit).
  • authorized: Boolean indicating whether ROOK is linked to this data source.
  • image: URL of the logo/icon for the corresponding data source.

For SDK-based data sources (e.g., Apple Health, Health Connect), authorized indicates if the user was created via SDK and linked with ROOK, but it does not confirm permission to access data.

For API-based data sources (e.g., Fitbit, Garmin, Withings), authorized: true confirms that the user has granted ROOK access to retrieve their data through the respective third-party platform.

You can see the full list of data sources here.

Authorizations:
basicAuth
path Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

Responses

Response samples

Content type
application/json
{}

[User][Information]

Fetches user information for the given user ID and date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "metadata": {
    },
  • "data_structure": "user_info",
  • "user_information": {
    }
}

[User][Time Zone]

Receives and updates the user's time zone information.

Authorizations:
basicAuth
path Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

Request Body schema: application/json
required

body

time_zone
string Continent/City

Specifies the user's time zone in the 'Continent/City' format, following the IANA Time Zone Database naming convention. This format ensures global standardization and prevents ambiguity.

offset
string +|- HH:MM

Represents the difference in hours and minutes between the specified time zone and Coordinated Universal Time (UTC). This offset allows precise time conversion across different regions. This offset should align with the standard time difference of the provided time_zone field.

Responses

Request samples

Content type
application/json
{
  • "time_zone": "America/Los_Angeles",
  • "offset": "-08:00"
}

Response samples

Content type
application/json
{
  • "message": "Time zone and offset successfully updated for the user."
}

[User][Information]

User information receives and processes user information from users

Authorizations:
basicAuth
Request Body schema: application/json
required

body

datetime
string <date-time> (datetime_iso8601)

Date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.sssZ).

user_id
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
date_of_birth_string
string <date>
height_cm_int
integer
weight_kg_float
number <float>
bmi_float
number <float>
sex_string
string

Responses

Request samples

Content type
application/json
{
  • "datetime": "2023-12-29T21:07:14.402999Z",
  • "user_id": "demoUserId",
  • "date_of_birth_string": "2024-04-21",
  • "height_cm_int": 0,
  • "weight_kg_float": 0.1,
  • "bmi_float": 0.1,
  • "sex_string": "male"
}

Response samples

Content type
application/json
{
  • "message": "added"
}

[User][Data Sources][Revoke]

Revokes user authorization for the specified data source.

Authorizations:
basicAuth
path Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

Request Body schema: application/json
required

body

data_source
string

Must be one of Garmin, Oura, Apple Health, Health Connect, Android, Polar, Fitbit, Withings, Whoop.

Responses

Request samples

Content type
application/json
{
  • "data_source": "Polar"
}

Response samples

Content type
application/json
{
  • "message": "Authorization for the specified user data source has been successfully revoked"
}

ROOK > Connect > Client

[Client][Webhooks][Resend Notification]

Endpoint to resend rejected notifications

Authorizations:
basicAuth
Request Body schema: application/json
required

body

start
string <date>
finish
string <date>

Responses

Request samples

Content type
application/json
{
  • "start": "2024-04-20",
  • "finish": "2024-04-21"
}

Response samples

Content type
application/json
{
  • "message": "Success",
  • "total_docs_to_resend": 29
}

[Client][Users][Status]

This endpoint allows clients to check the authorization status of their users across various data sources on a specific date. It provides the total number of users, their activity status, and detailed authorization information.

Authorizations:
basicAuth
query Parameters
up_to_date
required
string <date> ^d{4}-d{2}-d{2}$
Example: up_to_date=2025-01-15

Date in YYYY-MM-DD format that defines the limit for the endpoint data. It cannot be in the future and must be no more than 6 months prior to the current date.

page
integer <int32>
Example: page=1

Specifies the page number to retrieve in a paginated response. If not provided, defaults to page 1.

Responses

Response samples

Content type
application/json
{
  • "up_to_date": "2025-01-25",
  • "total_created_users": 2500,
  • "total_active_users": 359,
  • "users": [
    ],
  • "pagination": {
    }
}

ROOK > Connect > Physical Health

[Physical][Summary]

Fetches a summary of the user's physical health data for a specified date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "data_structure": "physical_summary",
  • "physical_health": {
    }
}

[Physical][Events][Activity]

Retrieves activity event data for the specified user over a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "activity_event",
  • "physical_health": {
    }
}

[Physical][Events][Heart Rate]

Fetches heart rate event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "heart_rate_event",
  • "physical_health": {
    }
}

[Physical][Events][Oxygenation]

Retrieves oxygenation event data for a specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "oxygenation_event",
  • "physical_health": {
    }
}

[Physical][Events][Stress]

Retrieves stress event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "stress_event",
  • "physical_health": {
    }
}

ROOK > Connect > Sleep Health

[Sleep][Summary]

Retrieves a summary of the user's sleep health data for a specified date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "data_structure": "sleep_summary",
  • "sleep_health": {
    }
}

ROOK > Connect > Body Health

[Body][Summary]

Retrieves a summary of the user's body health data for a specified date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "data_structure": "body_summary",
  • "body_health": {
    }
}

[Body][Events][Body Metrics]

Retrieves body metrics event data for a specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "body_metrics_event",
  • "body_health": {
    }
}

[Body][Events][Heart Rate]

Retrieves heart rate event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "heart_rate_event",
  • "body_health": {
    }
}

[Body][Events][Oxygenation]

Retrieves oxygenation event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "oxygenation_event",
  • "body_health": {
    }
}

[Body][Events][Nutrition]

Retrieves nutrition event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "nutrition_event",
  • "body_health": {
    }
}

[Body][Events][Mood]

Retrieves mood event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "mood_event",
  • "body_health": {
    }
}

[Body][Events][Hydration]

Retrieves hydration event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "hydration_event",
  • "body_health": {
    }
}

[Body][Events][Blood Glucose]

Retrieves blood glucose event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "blood_glucose_event",
  • "body_health": {
    }
}

[Body][Events][Blood Pressure]

Retrieves blood pressure event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "blood_pressure_event",
  • "body_health": {
    }
}

[Body][Events][Temperature]

Retrieves body temperature event data for the specified user on a given date.

Authorizations:
basicAuth
query Parameters
user_id
required
string (schema_user_id) ^[a-zA-Z0-9\-]{1,50}$
Example: user_id=demoUserId

Unique identifier for the user. Can include numerals, UUID4, strings, or other identifiers. Length must be between 1 to 50 characters.

date
required
string <date>
Example: date=2023-01-01

Date in YYYY-MM-DD format.

Responses

Response samples

Content type
application/json
{
  • "client_uuid": "demoClientUUID",
  • "user_id": "demoUserId",
  • "version": 2,
  • "document_version": 1,
  • "auto_detected": false,
  • "data_structure": "temperature_event",
  • "body_health": {
    }
}