> For the complete documentation index, see [llms.txt](https://developer.cudis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.cudis.xyz/infrastructure/cudis-apis/api-v1.md).

# 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:<br>

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.&#x20;

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.&#x20;

### 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**

<mark style="color:green;">`GET`</mark> `/oauth/authorize`

**Parameter**

<table><thead><tr><th width="156">Name</th><th width="114">Required?</th><th width="123">Type</th><th>Description</th></tr></thead><tbody><tr><td>response_type</td><td>Required</td><td>string</td><td>Value must be <code>token</code></td></tr><tr><td>client_id</td><td>Required</td><td>string</td><td>Your developer application's client ID.</td></tr><tr><td>redirect_uri</td><td>Optional</td><td>string</td><td>The URL to which the user will be redirected after successful authorization, typically the developer’s callback URL.</td></tr></tbody></table>

Example authorization request:

{% embed url="<https://accounts.cudis.ai/oauth/authorize?response_type=token&client_id=JDS734JSNDPW&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback>" %}

#### **2. Cudis redirects back to your site**

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

**Parameter**

<table><thead><tr><th width="173">Name</th><th width="91">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>access_token</code></td><td>string</td><td>An alphanumerical string. This is a new access token that can be used to access the user's data through the CUDIS API.</td></tr><tr><td><code>scope</code></td><td>string</td><td>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.</td></tr></tbody></table>

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.

<mark style="color:green;">`GET`</mark> `/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**

<table><thead><tr><th width="159">Name</th><th width="92">Type</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>Cudis-Client-Id</td><td>string</td><td><code>eg. "cudis-wellness"</code></td><td>The client ID of the user, used to verify and identify the API request source.</td></tr><tr><td>Authorization</td><td>string</td><td><code>Bearer &#x3C;token></code></td><td>Contains the user’s authorized access token to ensure secure API calls.</td></tr></tbody></table>

**Body**

<table><thead><tr><th width="145">Name</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>startTime</code></td><td>number</td><td>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).</td></tr><tr><td><code>endTime</code></td><td>number</td><td>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).</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
            }
        ]
    }
}
```

{% endtab %}

{% tab title="20007" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`GET`</mark> `/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**

<table><thead><tr><th width="159">Name</th><th width="92">Type</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>Cudis-Client-Id</td><td>string</td><td><code>eg. "cudis-wellness"</code></td><td>The client ID of the user, used to verify and identify the API request source.</td></tr><tr><td>Authorization</td><td>string</td><td><code>Bearer &#x3C;token></code></td><td>Contains the user’s authorized access token to ensure secure API calls.</td></tr></tbody></table>

**Body**

<table><thead><tr><th width="145">Name</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>startTime</code></td><td>number</td><td>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).</td></tr><tr><td><code>endTime</code></td><td>number</td><td>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).</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
            }
        ]
    }
}
```

{% endtab %}

{% tab title="20007" %}

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

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`GET`</mark> `/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**

<table><thead><tr><th width="159">Name</th><th width="92">Type</th><th>Value</th><th>Description</th></tr></thead><tbody><tr><td>Cudis-Client-Id</td><td>string</td><td><code>eg. "cudis-wellness"</code></td><td>The client ID of the user, used to verify and identify the API request source.</td></tr><tr><td>Authorization</td><td>string</td><td><code>Bearer &#x3C;token></code></td><td>Contains the user’s authorized access token to ensure secure API calls.</td></tr></tbody></table>

**Body**

<table><thead><tr><th width="145">Name</th><th width="105">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>startTime</code></td><td>number</td><td>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).</td></tr><tr><td><code>endTime</code></td><td>number</td><td>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).</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
            }
        ]
    }
}
```

{% endtab %}

{% tab title="20007" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.cudis.xyz/infrastructure/cudis-apis/api-v1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.