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]