Oura Sleep Routes API
The Sleep Routes API from Oura — 2 operation(s) for sleep routes.
OpenAPI Specification
openapi: 3.1.0
info:
title: Oura Daily Activity Routes Sleep Routes API
version: '2.0'
tags:
- name: Sleep Routes
paths:
/v2/usercollection/sleep:
get:
tags:
- Sleep Routes
summary: Multiple Sleep Documents
operationId: Multiple_sleep_Documents_v2_usercollection_sleep_get
parameters:
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: string
format: date
- type: 'null'
title: Start Date
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: string
format: date
- type: 'null'
title: End Date
- name: next_token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Next Token
- name: fields
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of fields to include in the response, in addition to the always returned fields. Defaults to all fields if not provided.
title: Fields
description: Comma-separated list of fields to include in the response, in addition to the always returned fields. Defaults to all fields if not provided.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/MultiDocumentResponse_PublicModifiedSleepModel_'
- $ref: '#/components/schemas/MultiDocumentResponseDict'
title: Response Multiple Sleep Documents V2 Usercollection Sleep Get
'400':
description: Client Exception
'401':
description: Unauthorized access exception. Usually means the access token is expired, malformed or revoked.
'403':
description: Access forbidden. Usually means the user's subscription to Oura has expired and their data is not available via the API.
'429':
description: Request Rate Limit Exceeded.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
- OAuth2: []
x-codeSamples:
- lang: cURL
label: cURL
source: 'curl --location --request GET ''https://api.ouraring.com/v2/usercollection/sleep?start_date=2021-11-01&end_date=2021-12-01&fields=day,score'' \
--header ''Authorization: Bearer <token>'''
- lang: Python
source: "import requests \nurl = 'https://api.ouraring.com/v2/usercollection/sleep' \nparams={ \n 'start_date': '2021-11-01', \n 'end_date': '2021-12-01',\n 'fields': 'day,score' \n}\nheaders = { \n 'Authorization': 'Bearer <token>' \n}\nresponse = requests.request('GET', url, headers=headers, params=params) \nprint(response.text)"
label: Python
- lang: JavaScript
source: "var myHeaders = new Headers(); \nmyHeaders.append('Authorization', 'Bearer <token>'); \nvar requestOptions = { \n method: 'GET', \n headers: myHeaders, \nfetch('https://api.ouraring.com/v2/usercollection/sleep?start_date=2021-11-01&end_date=2021-12-01&fields=day,score', requestOptions) \n .then(response => response.text()) \n .then(result => console.log(result)) \n .catch(error => console.log('error', error));"
label: JavaScript
- lang: Java
source: "OkHttpClient client = new OkHttpClient().newBuilder() \n .build(); \nRequest request = new Request.Builder() \n .url(\"https://api.ouraring.com/v2/usercollection/sleep?start_date=2021-11-01&end_date=2021-12-01&fields=day,score\") \n .method(\"GET\", null) \n .addHeader(\"Authorization\", \"Bearer <token>\") \n .build(); \nResponse response = client.newCall(request).execute();"
label: Java
/v2/usercollection/sleep/{document_id}:
get:
tags:
- Sleep Routes
summary: Single Sleep Document
operationId: Single_sleep_Document_v2_usercollection_sleep__document_id__get
parameters:
- name: document_id
in: path
required: true
schema:
type: string
title: Document Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicModifiedSleepModel'
'404':
description: Not Found
'400':
description: Client Exception
'401':
description: Unauthorized access exception. Usually means the access token is expired, malformed or revoked.
'403':
description: Access forbidden. Usually means the user's subscription to Oura has expired and their data is not available via the API.
'429':
description: Request Rate Limit Exceeded.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- BearerAuth: []
- OAuth2: []
x-codeSamples:
- lang: cURL
label: cURL
source: 'curl --location --request GET ''https://api.ouraring.com/v2/usercollection/sleep/2-5daccc095220cc5493a4e9c2b681ca941e'' \
--header ''Authorization: Bearer <token>'''
- lang: Python
source: "import requests \nurl = 'https://api.ouraring.com/v2/usercollection/sleep/2-5daccc095220cc5493a4e9c2b681ca941e\nheaders = { \n 'Authorization': 'Bearer <token>' \n}\nresponse = requests.request('GET', url, headers=headers, params=params) \nprint(response.text)"
label: Python
- lang: JavaScript
source: "var myHeaders = new Headers(); \nmyHeaders.append('Authorization', 'Bearer <token>'); \nvar requestOptions = { \n method: 'GET', \n headers: myHeaders, \nfetch('https://api.ouraring.com/v2/usercollection/sleep/2-5daccc095220cc5493a4e9c2b681ca941e', requestOptions) \n .then(response => response.text()) \n .then(result => console.log(result)) \n .catch(error => console.log('error', error));"
label: JavaScript
- lang: Java
source: "OkHttpClient client = new OkHttpClient().newBuilder() \n .build(); \nRequest request = new Request.Builder() \n .url(\"https://api.ouraring.com/v2/usercollection/sleep/2-5daccc095220cc5493a4e9c2b681ca941e\") \n .method(\"GET\", null) \n .addHeader(\"Authorization\", \"Bearer <token>\") \n .build(); \nResponse response = client.newCall(request).execute();"
label: Java
components:
schemas:
PublicReadinessContributors:
properties:
activity_balance:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of cumulative activity balance in range [1, 100].
body_temperature:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of body temperature in range [1, 100].
hrv_balance:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of heart rate variability balance in range [1, 100].
previous_day_activity:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of previous day's activity in range [1, 100].
previous_night:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of previous night's sleep in range [1, 100].
recovery_index:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of recovery index in range [1, 100].
resting_heart_rate:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of resting heart rate in range [1, 100].
sleep_balance:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of sleep balance in range [1, 100].
sleep_regularity:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Contribution of sleep regularity in range [1, 100].
type: object
title: PublicReadinessContributors
description: Object defining readiness score contributors.
ISODate:
type: string
PublicSleepAnalysisReason:
type: string
enum:
- foreground_sleep_analysis
- bedtime_edit
title: PublicSleepAnalysisReason
description: Possible sleep analysis reasons.
UtcDateTime:
type: string
LocalizedDateTime:
type: string
PublicSleepType:
type: string
enum:
- deleted
- sleep
- long_sleep
- late_nap
- rest
title: PublicSleepType
description: 'Possible sleep period types.
''deleted'' = deleted sleep by user.
''sleep'' = user confirmed sleep / nap, min 15 minutes, max 3 hours, contributes to daily scores
''late_nap'' = user confirmed sleep / nap, min 15 minutes, ended after sleep day change (6 pm), contributes to next days daily scores
''long_sleep'' = sleep that is long enough (>3h) to automatically contribute to daily scores
''rest'' = Falsely detected sleep / nap, rejected in confirm prompt by user'
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicModifiedSleepModel:
properties:
id:
type: string
minLength: 1
title: ''
description: Unique identifier of the object.
meta:
$ref: '#/components/schemas/Metadata'
title: ''
description: Meta data of the object.
average_breath:
anyOf:
- type: number
- type: 'null'
title: ''
description: Average breathing rate during sleep as breaths/minute.
average_heart_rate:
anyOf:
- type: number
- type: 'null'
title: ''
description: 'Average heart rate during sleep as beats/minute. NOTE: this is the average calculated by ecore (based on 30-second samples) which is different from what is shown in the app. The app shows the average of aggregated 5-minute heart rate samples.'
average_hrv:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Average heart rate variability during sleep.
awake_time:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Duration spent awake in seconds.
bedtime_end:
$ref: '#/components/schemas/LocalizedDateTime'
title: ''
description: Bedtime end of the sleep.
bedtime_start:
$ref: '#/components/schemas/LocalizedDateTime'
title: ''
description: Bedtime start of the sleep.
day:
$ref: '#/components/schemas/ISODate'
title: ''
description: Day that the sleep belongs to.
deep_sleep_duration:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Duration spent in deep sleep in seconds.
efficiency:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Sleep efficiency rating in range [1, 100].
heart_rate:
anyOf:
- $ref: '#/components/schemas/PublicSample'
- type: 'null'
title: ''
description: Object containing heart rate samples.
hrv:
anyOf:
- $ref: '#/components/schemas/PublicSample'
- type: 'null'
title: ''
description: Object containing heart rate variability samples.
latency:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Sleep latency in seconds. This is the time it took for the user to fall asleep after going to bed.
light_sleep_duration:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Duration spent in light sleep in seconds.
low_battery_alert:
type: boolean
title: ''
description: Flag indicating if a low battery alert occurred.
lowest_heart_rate:
anyOf:
- type: integer
- type: 'null'
title: ''
description: 'Lowest heart rate during sleep. NOTE: this is the value calculated by ecore (based on 30-second samples) which is different from what is shown in the app. The app shows the minimum of aggregated 5-minute heart rate samples.'
movement_30_sec:
anyOf:
- type: string
- type: 'null'
title: ''
description: '30-second movement classification for the period where every character corresponds to:
''1'' = no motion,
''2'' = restless,
''3'' = tossing and turning
''4'' = active
Example: "1143222134".'
period:
type: integer
title: ''
description: ECore sleep period identifier.
readiness:
anyOf:
- $ref: '#/components/schemas/PublicReadiness'
- type: 'null'
title: ''
description: Object containing the readiness details.
readiness_score_delta:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Effect on readiness score caused by this sleep period.
rem_sleep_duration:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Duration spent in REM sleep in seconds.
restless_periods:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Number of restless periods during sleep.
sleep_algorithm_version:
anyOf:
- $ref: '#/components/schemas/PublicSleepAlgorithmVersion'
- type: 'null'
title: ''
description: Version of the sleep algorithm used to calculate the sleep data.
sleep_analysis_reason:
anyOf:
- $ref: '#/components/schemas/PublicSleepAnalysisReason'
- type: 'null'
title: ''
description: The reason for the creation or update of the latest version of this sleep.
sleep_phase_30_sec:
anyOf:
- type: string
- type: 'null'
title: ''
description: '30-second sleep phase classification for the period where every character corresponds to:
''1'' = deep sleep,
''2'' = light sleep,
''3'' = REM sleep
''4'' = awake.
Example: "444423323441114".'
sleep_phase_5_min:
anyOf:
- type: string
- type: 'null'
title: ''
description: '5-minute sleep phase classification for the period where every character corresponds to:
''1'' = deep sleep,
''2'' = light sleep,
''3'' = REM sleep
''4'' = awake.
Example: "444423323441114".'
sleep_score_delta:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Effect on sleep score caused by this sleep period.
time_in_bed:
type: integer
title: ''
description: Duration spent in bed in seconds.
total_sleep_duration:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Total sleep duration in seconds.
type:
anyOf:
- $ref: '#/components/schemas/PublicSleepType'
- type: 'null'
title: ''
description: Type of the sleep period.
ring_id:
anyOf:
- type: string
- type: 'null'
title: Ring Id
description: Encrypted identifier of the ring that produced this sleep data.
app_sleep_phase_5_min:
anyOf:
- type: string
- type: 'null'
title: App Sleep Phase 5 Min
description: "\n 5-minute sleep phase classification for the period aligned with what is shown in the app\n where every character corresponds to:\n '1' = deep sleep,\n '2' = light sleep,\n '3' = REM sleep\n '4' = awake.\n Example: \"444423323441114\".\n NOTE: This field will be removed in the future after a transition period.\n "
type: object
required:
- id
- meta
- bedtime_end
- bedtime_start
- day
- low_battery_alert
- period
- time_in_bed
title: PublicModifiedSleepModel
x-cloud-only: true
x-collection: publicsleepmodel
x-owner: health-squad
PublicSample:
properties:
interval:
type: number
title: ''
description: Interval in seconds between the sampled items.
items:
$ref: '#/components/schemas/Array_Union_float__NoneType__Bits64_'
title: ''
description: Recorded sample items.
timestamp:
$ref: '#/components/schemas/LocalizedDateTime'
title: ''
description: Timestamp when the sample recording started.
type: object
required:
- interval
- items
- timestamp
title: PublicSample
description: Object defining a recorded sample.
Array_Union_float__NoneType__Bits64_:
items:
anyOf:
- type: number
- type: 'null'
type: array
title: ArrayNullableFloatBits64
Metadata:
properties:
updated_at:
$ref: '#/components/schemas/UtcDateTime'
title: ''
description: Timestamp indicating when the object was last updated.
version:
type: integer
title: ''
description: Version number of the object.
type: object
required:
- updated_at
- version
title: Metadata
description: Object defining the metadata of a collection model instance.
PublicReadiness:
properties:
contributors:
$ref: '#/components/schemas/PublicReadinessContributors'
title: ''
description: Contributors of the readiness score.
score:
anyOf:
- type: integer
- type: 'null'
title: ''
description: Readiness score in range [1, 100].
temperature_deviation:
anyOf:
- type: number
- type: 'null'
title: ''
description: Temperature deviation in degrees Celcius.
temperature_trend_deviation:
anyOf:
- type: number
- type: 'null'
title: ''
description: Temperature trend deviation in degrees Celcius.
type: object
required:
- contributors
title: PublicReadiness
description: Object defining readiness.
PublicSleepAlgorithmVersion:
type: string
enum:
- v1
- v2
title: PublicSleepAlgorithmVersion
description: 'Oura Sleep Staging Algorithms.
v1 = original aka legacy aka OSSA 1.0,
v2 = latest sleep algorithm'
MultiDocumentResponseDict:
properties:
data:
items:
additionalProperties: true
type: object
type: array
title: Data
next_token:
anyOf:
- type: string
- type: 'null'
title: Next Token
type: object
required:
- data
- next_token
title: MultiDocumentResponseDict
MultiDocumentResponse_PublicModifiedSleepModel_:
properties:
data:
items:
$ref: '#/components/schemas/PublicModifiedSleepModel'
type: array
title: Data
next_token:
anyOf:
- type: string
- type: 'null'
title: Next Token
type: object
required:
- data
- next_token
title: MultiDocumentResponse[PublicModifiedSleepModel]