OuraToolkit.Api 0.3.0

OuraToolkit.Api - the C# library for the Oura API Documentation

Overview

The Oura API allows Oura users and partner applications to improve their user experience with Oura data. This document describes the Oura API Version 2 (V2), which is the only available integration point for Oura data. The previous V1 API has been sunset.

Getting Started

What is an API?

An API (Application Programming Interface) allows different software applications to communicate with each other. The Oura API enables you to access your Oura Ring data programmatically.

Quick Start Guide

1. Register an API Application and implement OAuth2
2. Make Your First API Call:

   curl -X GET https://api.ouraring.com/v2/usercollection/personal_info \\
   -H \"Authorization: Bearer YOUR_TOKEN_HERE\"
   

3. Explore Data Types:
   • Browse the available endpoints in this documentation to discover what data you can access
   • Each endpoint includes example requests and responses
4. Set Up Webhooks (Strongly Recommended):
   • Webhooks are the preferred way to consume Oura data
   • We have not had customers hit rate limits with webhooks properly implemented
   • Make a single request for historical data when a user first connects, then use webhooks for ongoing updates
   • Webhook notifications come approximately 30 seconds after data syncs from the mobile app
   • Set up webhooks to receive notifications when data changes

Common Questions

• Data Delay: Different data types sync at different times - sleep data requires users to open the Oura app, while daily activity and stress may sync in the background

Data Access

In order to access data, a registered API Application is required. API Applications are limited to 10 users before requiring approval from Oura. There is no limit once an application is approved. Additionally, Oura users must provide consent to share each data type an API Application has access to. All data access requests through the Oura API require Authentication. Additionally, we recommend that Oura users keep their mobile app updated to support API access for the latest data types.

Authentication

The Oura Cloud API supports authentication through the industry-standard OAuth2 protocol. For more information, see our Authentication instructions. Access tokens must be included in the request header as follows:

GET /v2/usercollection/personal_info HTTP/1.1
Host: api.ouraring.com
Authorization: Bearer <token>

Please note that personal access tokens were deprecated in December 2025 and are no longer available for use.

Oura HTTP Response Codes

| Response Code | Description | | - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - | - | | 200 OK | Successful Response | | 400 Query Parameter Validation Error | The request contains query parameters that are invalid or incorrectly formatted. | | 401 Unauthorized | Invalid or expired authentication token. | | 403 Forbidden | The requested resource requires additional permissions or the user's Oura subscription has expired. | | 429 Too Many Requests | Rate limit exceeded. See response headers for retry guidance. |

Rate Limits

The API enforces rate limits at two layers to ensure fair access across all applications:

• a per-access-token limit, which throttles single-token floods, and
• a per-application limit, which caps the aggregate traffic across all of an application's end-user tokens so one fan-out app can't dominate shared capacity.

A request that trips either layer receives a 429 Too Many Requests. The X-RateLimit-Tier response header identifies which layer fired.

If your application regularly approaches rate limits, webhooks are strongly recommended — most applications that implement webhooks correctly do not encounter rate limit issues.

Contact us if you expect your usage to require higher limits.

Rate Limit Response Headers

When a 429 Too Many Requests response is returned, five headers are included to guide retries. Prefer these over fixed-interval backoff:

• Retry-After — integer seconds to wait before retrying. RFC 7231-compliant; safe to feed directly into your client's backoff logic.
• X-RateLimit-Limit — the request ceiling for the current window.
• X-RateLimit-Window — the rolling window length in seconds that the ceiling applies to.
• X-RateLimit-Reset — Unix epoch (seconds) at which the window resets and quota is fully restored.
• X-RateLimit-Tier — identifies which limit was exceeded, useful when contacting support.

This C# SDK is automatically generated by the OpenAPI Generator project:

• API version: 2.0
• SDK version: 0.3.0
• Generator version: 7.14.0
• Build package: org.openapitools.codegen.languages.CSharpClientCodegen

<a id="frameworks-supported"></a>

Frameworks supported

• .NET Core >=1.0
• .NET Framework >=4.6
• Mono/Xamarin >=vNext

<a id="dependencies"></a>

Dependencies

• Json.NET - 13.0.2 or later
• JsonSubTypes - 1.8.0 or later
• System.ComponentModel.Annotations - 5.0.0 or later

The DLLs included in the package may not be the latest version. We recommend using NuGet to obtain the latest version of the packages:

Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
Install-Package System.ComponentModel.Annotations

<a id="installation"></a>

Installation

Generate the DLL using your preferred tool (e.g. dotnet build)

Then include the DLL (under the bin folder) in the C# project, and use the namespaces:

using OuraToolkit.Api.Api;
using OuraToolkit.Api.Client;
using OuraToolkit.Api.Model;

<a id="usage"></a>

Usage

To use the API client with a HTTP proxy, setup a System.Net.WebProxy

Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;

Connections

Each ApiClass (properly the ApiClient inside it) will create an instance of HttpClient. It will use that for the entire lifecycle and dispose it when called the Dispose method.

To better manager the connections it's a common practice to reuse the HttpClient and HttpClientHandler (see here for details). To use your own HttpClient instance just pass it to the ApiClass constructor.

HttpClientHandler yourHandler = new HttpClientHandler();
HttpClient yourHttpClient = new HttpClient(yourHandler);
var api = new YourApiClass(yourHttpClient, yourHandler);

If you want to use an HttpClient and don't have access to the handler, for example in a DI context in Asp.net Core when using IHttpClientFactory.

HttpClient yourHttpClient = new HttpClient();
var api = new YourApiClass(yourHttpClient);

You'll loose some configuration settings, the features affected are: Setting and Retrieving Cookies, Client Certificates, Proxy settings. You need to either manually handle those in your setup of the HttpClient or they won't be available.

Here an example of DI setup in a sample web project:

services.AddHttpClient<YourApiClass>(httpClient =>
   new PetApi(httpClient));

<a id="getting-started"></a>

Getting Started

using System.Collections.Generic;
using System.Diagnostics;
using System.Net.Http;
using OuraToolkit.Api.Api;
using OuraToolkit.Api.Client;
using OuraToolkit.Api.Model;

namespace Example
{
    public class Example
    {
        public static void Main()
        {

            Configuration config = new Configuration();
            config.BasePath = "https://api.ouraring.com";
            // Configure Bearer token for authorization: BearerAuth
            config.AccessToken = "YOUR_BEARER_TOKEN";

            // create instances of HttpClient, HttpClientHandler to be reused later with different Api classes
            HttpClient httpClient = new HttpClient();
            HttpClientHandler httpClientHandler = new HttpClientHandler();
            var apiInstance = new DailyActivityRoutesApi(httpClient, config, httpClientHandler);
            var startDate = DateTime.Parse("2013-10-20");  // DateTime? |  (optional) 
            var endDate = DateTime.Parse("2013-10-20");  // DateTime? |  (optional) 
            var nextToken = "nextToken_example";  // string? |  (optional) 
            var fields = "fields_example";  // string? | Comma-separated list of fields to include in the response, in addition to the always returned fields. Defaults to all fields if not provided. (optional) 

            try
            {
                // Multiple Daily Activity Documents
                MultiDocumentResponsePublicDailyActivity result = apiInstance.MultipleDailyActivityDocumentsV2UsercollectionDailyActivityGet(startDate, endDate, nextToken, fields);
                Debug.WriteLine(result);
            }
            catch (ApiException e)
            {
                Debug.Print("Exception when calling DailyActivityRoutesApi.MultipleDailyActivityDocumentsV2UsercollectionDailyActivityGet: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }

        }
    }
}

<a id="documentation-for-api-endpoints"></a>

Documentation for API Endpoints

All URIs are relative to https://api.ouraring.com

<a id="documentation-for-models"></a>

Documentation for Models

• Model.CreateWebhookSubscriptionRequest
• Model.DailyResilienceModel
• Model.EnhancedTagModel
• Model.ExtApiV2DataType
• Model.HTTPValidationError
• Model.LongTermResilienceLevel
• Model.MultiDocumentResponseDailyResilienceModel
• Model.MultiDocumentResponseEnhancedTagModel
• Model.MultiDocumentResponsePublicDailyActivity
• Model.MultiDocumentResponsePublicDailyCardiovascularAge
• Model.MultiDocumentResponsePublicDailyReadiness
• Model.MultiDocumentResponsePublicDailySleep
• Model.MultiDocumentResponsePublicDailySpO2
• Model.MultiDocumentResponsePublicDailyStress
• Model.MultiDocumentResponsePublicModifiedSleepModel
• Model.MultiDocumentResponsePublicRestModePeriod
• Model.MultiDocumentResponsePublicRingConfiguration
• Model.MultiDocumentResponsePublicSession
• Model.MultiDocumentResponsePublicSleepTime
• Model.MultiDocumentResponsePublicVO2Max
• Model.MultiDocumentResponsePublicWorkout
• Model.MultiDocumentResponseTagModel
• Model.PersonalInfoResponse
• Model.PublicActivityContributors
• Model.PublicDailyActivity
• Model.PublicDailyCardiovascularAge
• Model.PublicDailyReadiness
• Model.PublicDailySleep
• Model.PublicDailySpO2
• Model.PublicDailyStress
• Model.PublicDailyStressSummary
• Model.PublicHeartRateRow
• Model.PublicHeartRateSource
• Model.PublicModifiedSleepModel
• Model.PublicMomentMood
• Model.PublicMomentType
• Model.PublicReadiness
• Model.PublicReadinessContributors
• Model.PublicRestModeEpisode
• Model.PublicRestModePeriod
• Model.PublicRingBatteryLevelRow
• Model.PublicRingColor
• Model.PublicRingConfiguration
• Model.PublicRingDesign
• Model.PublicRingHardwareType
• Model.PublicSample
• Model.PublicSession
• Model.PublicSleepAlgorithmVersion
• Model.PublicSleepAnalysisReason
• Model.PublicSleepContributors
• Model.PublicSleepTime
• Model.PublicSleepTimeRecommendation
• Model.PublicSleepTimeStatus
• Model.PublicSleepTimeWindow
• Model.PublicSleepType
• Model.PublicSpo2AggregatedValues
• Model.PublicVO2Max
• Model.PublicWorkout
• Model.PublicWorkoutIntensity
• Model.PublicWorkoutSource
• Model.ResilienceContributors
• Model.ResponseMultipleHeartrateDocumentsV2UsercollectionHeartrateGet
• Model.ResponseMultipleRingBatteryLevelDocumentsV2UsercollectionRingBatteryLevelGet
• Model.ResponseSandboxMultipleHeartrateDocumentsV2SandboxUsercollectionHeartrateGet
• Model.ResponseSandboxMultipleRingBatteryLevelDocumentsV2SandboxUsercollectionRingBatteryLevelGet
• Model.TagModel
• Model.TimeSeriesResponseDict
• Model.TimeSeriesResponsePublicHeartRateRow
• Model.TimeSeriesResponsePublicRingBatteryLevelRow
• Model.UpdateWebhookSubscriptionRequest
• Model.ValidationError
• Model.ValidationErrorLocInner
• Model.WebhookOperation
• Model.WebhookSubscriptionModel

<a id="documentation-for-authorization"></a>

Documentation for Authorization

Authentication schemes defined for the API: <a id="BearerAuth"></a>

BearerAuth

• Type: Bearer Authentication

<a id="OAuth2"></a>

OAuth2

• Type: OAuth
• Flow: accessCode
• Authorization URL: https://cloud.ouraring.com/oauth/authorize
• Scopes:
  • email: Email address of the user
  • personal: Personal information (gender, age, height, weight)
  • daily: Daily summaries of sleep, activity and readiness
  • heartrate: Time series heart rate for Gen 3 users
  • workout: Summaries for auto-detected and user entered workouts
  • tag: User entered tags
  • session: Guided and unguided sessions in the Oura app
  • spo2Daily: SpO2 Average recorded during sleep

<a id="ClientIdAuth"></a>

ClientIdAuth

• Type: API key
• API key parameter name: x-client-id
• Location: HTTP header

<a id="ClientSecretAuth"></a>

ClientSecretAuth

• Type: API key
• API key parameter name: x-client-secret
• Location: HTTP header