API (V1)

Welcome to the CUDIS API (V1) documentation! This guide provides all the information you need to integrate with the CUDIS platform using our powerful set of APIs. Whether you’re developing a mobile app, a web application, or a service that leverages CUDIS Ring data, our APIs offer you the flexibility and control to build innovative solutions that enhance user experiences.

Getting Started

To begin integrating with the CUDIS API, please follow these steps:

1. Sign Up for API Access: Ensure you have registered for API access and received your API keys.

2. Read the Authentication Guide: Understand how to securely authenticate your requests.

3. Explore API Endpoints: Review the available endpoints and their functionalities to determine which ones are relevant to your project.

1. Sign Up for API Access

At this time, access to the CUDIS API is by invitation only. We are not yet supporting self-service registration through the developer portal, and Client-Ids are issued manually.

We appreciate your patience as we expand our platform and look forward to welcoming more developers in the future.

2. Read the Authentication Guide

Scopes

You can request access to 1 different scopes of user data:

• daily Daily summaries of sleep, step and heartbeat

When a CUDIS user authorizs access to your application, she can enable and disable scopes based on her preferences.

The Client-Side Only Flow

Note that the client-side only flow does not support refresh tokens. Once a token expires (currently set to 30 days), the user will need to re-authenticate your app.

1. Direct Users To Log Into CUDIS and Authorize Your App

GET /oauth/authorize

Parameter

Name	Required?	Type	Description
response_type	Required	string	Value must be token
client_id	Required	string	Your developer application's client ID.
redirect_uri	Optional	string	The URL to which the user will be redirected after successful authorization, typically the developer’s callback URL.

Example authorization request:

https://accounts.cudis.ai/oauth/authorize?response_type=token&client_id=JDS734JSNDPW&redirect_uri=https%3A%2F%2Fexample.com%2Fcallbackaccounts.cudis.ai

2. Cudis redirects back to your site

When the user grants access to your application, CUDIS will redirect them to your redirect URL.

Parameter

Name	Type	Description
access_token	string	An alphanumerical string. This is a new access token that can be used to access the user's data through the CUDIS API.
scope	string	A plus-sign (+) separated list of scopes that the access token is valid for. Note that this may be a subset of the requested scopes if the user chose not to grant access to all of the requested scopes.

The example authorization request above will result in the following redirect if the user authorizes the application:

https://example.com/callback?access_token=PHCW3OVMXQZX5FJUR6ZK4FAA2MK2CWWA&scope=daily

(The access_token will be different each time)

3. Explore API Endpoints

3.1 Retrieve the user’s heartbeat count for the specified time range.

GET /partner/v1/query/heart_beat

This endpoint retrieves the user’s heartbeat count for a specified time range. The query retrieves daily-level data for the specified period and does not include data for the current day.

Headers

Name	Type	Value	Description
Cudis-Client-Id	string	eg. "cudis-wellness"	The client ID of the user, used to verify and identify the API request source.
Authorization	string	Bearer <token>	Contains the user’s authorized access token to ensure secure API calls.

Body

Name	Type	Description
startTime	number	The Unix timestamp (in seconds) representing the start of the query range. This marks the beginning of the period for which step count data will be retrieved (inclusive).
endTime	number	The Unix timestamp (in seconds) representing the end of the query range. This marks the end of the period for which step count data will be retrieved (exclusive of the current day).

Response

200

{
    "code": 200,
    "msg": "success",
    "data": {
        "maximum": 80,
        "minimum": 60,
        "average": 73,
        "list": [
            {
                "date": "2024-09-16",
                "maxY": 80.0,
                "minY": 70.0
            },
            {
                "date": "2024-09-17",
                "maxY": 80.0,
                "minY": 60.0
            },
            {
                "date": "2024-09-18",
                "maxY": 80.0,
                "minY": 75.0
            }
        ]
    }
}

20007

Maybe the token has expired, or the 'Cudis-Client-Id' is invalid.
{
    "code": 20007,
    "msg": "Session expired. Please sign in again",
    "data": null
}

3.2 Retrieve the user’s step count for the specified time range.（In Development, Not Yet Available）

GET /partner/v1/query/step

This endpoint retrieves the user’s step count for a specified time range. The query retrieves daily-level data for the specified period and does not include data for the current day.

Headers

Name	Type	Value	Description
Cudis-Client-Id	string	eg. "cudis-wellness"	The client ID of the user, used to verify and identify the API request source.
Authorization	string	Bearer <token>	Contains the user’s authorized access token to ensure secure API calls.

Body

Name	Type	Description
startTime	number	The Unix timestamp (in seconds) representing the start of the query range. This marks the beginning of the period for which step count data will be retrieved (inclusive).
endTime	number	The Unix timestamp (in seconds) representing the end of the query range. This marks the end of the period for which step count data will be retrieved (exclusive of the current day).

Response

200

{
    "code": 200,
    "msg": "success",
    "data": {
        "countStep": 4291,
        "list": [
            {
                "date": "2024-09-16",
                "y": 2523.0
            },
            {
                "date": "2024-09-17",
                "y": 771.0
            },
            {

                "date": "2024-09-18",
                "y": 997.0
            }
        ]
    }
}

20007

Maybe the token has expired, or the 'Cudis-Client-Id' is invalid.
{
    "code": 20007,
    "msg": "Session expired. Please sign in again",
    "data": null
}

3.3 Retrieve the user’s sleep data for the specified time range.（In Development, Not Yet Available）

GET /partner/v1/query/sleep

This endpoint retrieves the user’s sleep for a specified time range. The query retrieves daily-level data for the specified period and does not include data for the current day.

Headers

Name	Type	Value	Description
Cudis-Client-Id	string	eg. "cudis-wellness"	The client ID of the user, used to verify and identify the API request source.
Authorization	string	Bearer <token>	Contains the user’s authorized access token to ensure secure API calls.

Body

Name	Type	Description
startTime	number	The Unix timestamp (in seconds) representing the start of the query range. This marks the beginning of the period for which step count data will be retrieved (inclusive).
endTime	number	The Unix timestamp (in seconds) representing the end of the query range. This marks the end of the period for which step count data will be retrieved (exclusive of the current day).

Response

200

{
    "code": 200,
    "msg": "success",
    "data": {
        "deepRatio": 10,
        "shallowRatio": 86,
        "awakeRatio": 4,
        "sumDuration": 431,
        "list": [
            {
                "date": "2024-09-15",
                "deepY": 59,
                "shallowY": 468,
                "awakeY": 7
            },
            {
                "date": "2024-09-16",
                "deepY": 37,
                "shallowY": 384,
                "awakeY": 20
            },
            {
                "date": "2024-09-17",
                "deepY": 44,
                "shallowY": 265,
                "awakeY": 10
            }
        ]
    }
}

20007

Maybe the token has expired, or the 'Cudis-Client-Id' is invalid.
{
    "code": 20007,
    "msg": "Session expired. Please sign in again",
    "data": null
}