Fulcra Sleep API

openapi: 3.2.0
info:
  contact:
    email: contact@fulcradynamics.com
    name: Fulcra Dynamics
    url: https://www.fulcradynamics.com/
  description: REST API for interacting with the Fulcra Platform and Data Store
  termsOfService: https://www.fulcradynamics.com/legal/terms-of-use
  title: Fulcra Life Sleep API
  version: 1.0.0
servers:
- url: https://api.fulcradynamics.com
  description: Fulcra Life API
security:
- bearerAuth: []
tags:
- name: Sleep
paths:
  /data/v0/{fulcra_userid}/sleep_agg:
    get:
      description: Process raw sleep data samples aggregated sleep stage durations per period.
      operationId: get_sleep_agg_data_v0__fulcra_userid__sleep_agg_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO8601 format (inclusive)
        examples:
          sample1:
            summary: November 15, 2024 at midnight UTC
            value: '2024-11-15 00:00:00Z'
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO8601 format (inclusive)
          examples:
          - '2024-11-15 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO8601 format (exclusive)
        examples:
          sample1:
            summary: November 16, 2024 at midnight UTC
            value: '2024-11-16 00:00:00Z'
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO8601 format (exclusive)
          examples:
          - '2024-11-16 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - description: The output format to generate.
        examples:
          example1:
            summary: JSON table (schema / data separation)
            value: jstable
          example2:
            summary: JSON columns (dict of columns)
            value: jscolumns
          example3:
            summary: Apache Arrow / Feather format
            value: arrow
          example4:
            summary: Parquet
            value: parquet
          example5:
            summary: Apache Arrow / Feather uncompressed
            value: arrowraw
          example6:
            summary: CSV
            value: csv
          example7:
            summary: CSV (quote everything)
            value: quotecsv
        in: query
        name: output
        required: true
        schema:
          $ref: '#/components/schemas/OutputMethod'
          description: The output format to generate.
      - description: Minimum time interval separating distinct cycles.
        in: query
        name: cycle_gap
        required: false
        schema:
          default: PT2H
          description: Minimum time interval separating distinct cycles.
          format: duration
          title: Cycle Gap
          type: string
      - description: Sleep stages to include. Defaults to all stages.
        in: query
        name: stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to include. Defaults to all stages.
          title: Stages
      - description: Sleep stages to consider as gaps in sleep cycles.
        in: query
        name: gap_stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to consider as gaps in sleep cycles.
          title: Gap Stages
      - description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
        in: query
        name: clip_to_range
        required: false
        schema:
          default: true
          description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
          title: Clip To Range
          type: boolean
      - description: Whether to use the cycle start or cycle end to assign cycles to periods, or to split sleep stage intervals at period boundries.
        in: query
        name: mode
        required: false
        schema:
          $ref: '#/components/schemas/Mode'
          default: end
          description: Whether to use the cycle start or cycle end to assign cycles to periods, or to split sleep stage intervals at period boundries.
      - description: The period start and interval represented with the polars string language (see https://docs.pola.rs/api/python/dev/reference/expressions/api/polars.Expr.dt.truncate.html).
        in: query
        name: period
        required: false
        schema:
          default: 1d
          description: The period start and interval represented with the polars string language (see https://docs.pola.rs/api/python/dev/reference/expressions/api/polars.Expr.dt.truncate.html).
          title: Period
          type: string
      - description: Aggregations to return.
        in: query
        name: agg_functions
        required: false
        schema:
          default:
          - sum
          description: Aggregations to return.
          items:
            $ref: '#/components/schemas/AggregateFunction'
          title: Agg Functions
          type: array
      - description: IANA time zone to return results in
        in: query
        name: tz
        required: false
        schema:
          default: UTC
          description: IANA time zone to return results in
          title: Tz
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return sleep cycles aggregated by a specified period
      tags:
      - Sleep
  /data/v0/{fulcra_userid}/sleep_cycles:
    get:
      description: 'Process raw sleep data samples into sleep cycles and assign

        by finding gaps in the sleep sample data within a specified time interval.'
      operationId: get_sleep_cycles_data_v0__fulcra_userid__sleep_cycles_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO8601 format (inclusive)
        examples:
          sample1:
            summary: November 15, 2024 at midnight UTC
            value: '2024-11-15 00:00:00Z'
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO8601 format (inclusive)
          examples:
          - '2024-11-15 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO8601 format (exclusive)
        examples:
          sample1:
            summary: November 16, 2024 at midnight UTC
            value: '2024-11-16 00:00:00Z'
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO8601 format (exclusive)
          examples:
          - '2024-11-16 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - description: The output format to generate.
        examples:
          example1:
            summary: JSON table (schema / data separation)
            value: jstable
          example2:
            summary: JSON columns (dict of columns)
            value: jscolumns
          example3:
            summary: Apache Arrow / Feather format
            value: arrow
          example4:
            summary: Parquet
            value: parquet
          example5:
            summary: Apache Arrow / Feather uncompressed
            value: arrowraw
          example6:
            summary: CSV
            value: csv
          example7:
            summary: CSV (quote everything)
            value: quotecsv
        in: query
        name: output
        required: true
        schema:
          $ref: '#/components/schemas/OutputMethod'
          description: The output format to generate.
      - description: Minimum time interval separating distinct cycles.
        in: query
        name: cycle_gap
        required: false
        schema:
          default: PT2H
          description: Minimum time interval separating distinct cycles.
          format: duration
          title: Cycle Gap
          type: string
      - description: Sleep stages to include. Defaults to all stages.
        in: query
        name: stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to include. Defaults to all stages.
          title: Stages
      - description: Sleep stages to consider as gaps in sleep cycles.
        in: query
        name: gap_stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to consider as gaps in sleep cycles.
          title: Gap Stages
      - description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
        in: query
        name: clip_to_range
        required: false
        schema:
          default: true
          description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
          title: Clip To Range
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return sleep cycles summarized from sleep stages
      tags:
      - Sleep
  /data/v0/{fulcra_userid}/sleep_cycles_extended:
    get:
      description: 'Extended version of sleep_cycles endpoint for experimentation.

        Adds metric time series data (heart rate, respiratory rate, etc.) to each sleep cycle.'
      operationId: get_sleep_cycles_extended_data_v0__fulcra_userid__sleep_cycles_extended_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO8601 format (inclusive)
        examples:
          sample1:
            summary: November 15, 2024 at midnight UTC
            value: '2024-11-15 00:00:00Z'
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO8601 format (inclusive)
          examples:
          - '2024-11-15 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO8601 format (exclusive)
        examples:
          sample1:
            summary: November 16, 2024 at midnight UTC
            value: '2024-11-16 00:00:00Z'
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO8601 format (exclusive)
          examples:
          - '2024-11-16 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - description: The output format to generate.
        examples:
          example1:
            summary: JSON table (schema / data separation)
            value: jstable
          example2:
            summary: JSON columns (dict of columns)
            value: jscolumns
          example3:
            summary: Apache Arrow / Feather format
            value: arrow
          example4:
            summary: Parquet
            value: parquet
          example5:
            summary: Apache Arrow / Feather uncompressed
            value: arrowraw
          example6:
            summary: CSV
            value: csv
          example7:
            summary: CSV (quote everything)
            value: quotecsv
        in: query
        name: output
        required: true
        schema:
          $ref: '#/components/schemas/OutputMethod'
          description: The output format to generate.
      - description: Minimum time interval separating distinct cycles.
        in: query
        name: cycle_gap
        required: false
        schema:
          default: PT2H
          description: Minimum time interval separating distinct cycles.
          format: duration
          title: Cycle Gap
          type: string
      - description: Sleep stages to include. Defaults to all stages.
        in: query
        name: stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to include. Defaults to all stages.
          title: Stages
      - description: Sleep stages to consider as gaps in sleep cycles.
        in: query
        name: gap_stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to consider as gaps in sleep cycles.
          title: Gap Stages
      - description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
        in: query
        name: clip_to_range
        required: false
        schema:
          default: true
          description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
          title: Clip To Range
          type: boolean
      - description: Optional list of metrics to include as time series data (e.g., HeartRate, RespiratoryRate).
        in: query
        name: metrics
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Optional list of metrics to include as time series data (e.g., HeartRate, RespiratoryRate).
          examples:
          - HeartRate
          - RespiratoryRate
          title: Metrics
      - description: Statistics to calculate for each time window in metric time series.
        examples:
          example1:
            summary: The maximum value for each time window.
            value: max
          example2:
            summary: The minimum value for each time window.
            value: min
          example3:
            summary: The mean value for each time window.
            value: mean
          example4:
            summary: The list of all values for each time window.
            value: allpoints
        in: query
        name: metric_calculations
        required: false
        schema:
          anyOf:
          - items:
              $ref: '#/components/schemas/TimeSeriesCalculation'
            type: array
          - type: 'null'
          description: Statistics to calculate for each time window in metric time series.
          title: Metric Calculations
      - description: Number of seconds before each sleep cycle to include in metric time series data.
        in: query
        name: metric_seconds_before
        required: false
        schema:
          default: 0
          description: Number of seconds before each sleep cycle to include in metric time series data.
          examples:
          - 3600
          - 7200
          minimum: 0
          title: Metric Seconds Before
          type: number
      - description: Number of seconds after each sleep cycle to include in metric time series data.
        in: query
        name: metric_seconds_after
        required: false
        schema:
          default: 0
          description: Number of seconds after each sleep cycle to include in metric time series data.
          examples:
          - 3600
          - 7200
          minimum: 0
          title: Metric Seconds After
          type: number
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return sleep cycles with extended data (experimental)
      tags:
      - Sleep
  /data/v0/{fulcra_userid}/sleep_stage_metadata:
    get:
      description: Retrieve metadata for interpreting sleep stage data, such as stage names and depths. In future, this may include user-specific stage or device priorities as well.
      operationId: get_sleep_stage_metadata
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return sleep stage metadata
      tags:
      - Sleep
  /data/v0/{fulcra_userid}/sleep_stages:
    get:
      description: 'Process raw sleep data samples into non-conflicting sleep stages and assign

        a cycle index by finding gaps in the sleep sample data within a specified time interval.


        If more than one sleep data source is present, sleep stage is determined based

        on the priority of the stage (in bed and unknown are deprioritized) and the

        start time of the sample (latest takes precedence)'
      operationId: get_sleep_stages_data_v0__fulcra_userid__sleep_stages_get
      parameters:
      - in: path
        name: fulcra_userid
        required: true
        schema:
          format: uuid
          title: Fulcra Userid
          type: string
      - description: The starting timestamp in ISO8601 format (inclusive)
        examples:
          sample1:
            summary: November 15, 2024 at midnight UTC
            value: '2024-11-15 00:00:00Z'
        in: query
        name: start_time
        required: true
        schema:
          description: The starting timestamp in ISO8601 format (inclusive)
          examples:
          - '2024-11-15 00:00:00Z'
          format: date-time
          title: Start Time
          type: string
      - description: The ending timestamp in ISO8601 format (exclusive)
        examples:
          sample1:
            summary: November 16, 2024 at midnight UTC
            value: '2024-11-16 00:00:00Z'
        in: query
        name: end_time
        required: true
        schema:
          description: The ending timestamp in ISO8601 format (exclusive)
          examples:
          - '2024-11-16 00:00:00Z'
          format: date-time
          title: End Time
          type: string
      - description: The output format to generate.
        examples:
          example1:
            summary: JSON table (schema / data separation)
            value: jstable
          example2:
            summary: JSON columns (dict of columns)
            value: jscolumns
          example3:
            summary: Apache Arrow / Feather format
            value: arrow
          example4:
            summary: Parquet
            value: parquet
          example5:
            summary: Apache Arrow / Feather uncompressed
            value: arrowraw
          example6:
            summary: CSV
            value: csv
          example7:
            summary: CSV (quote everything)
            value: quotecsv
        in: query
        name: output
        required: true
        schema:
          $ref: '#/components/schemas/OutputMethod'
          description: The output format to generate.
      - description: Minimum time interval separating distinct cycles.
        in: query
        name: cycle_gap
        required: false
        schema:
          default: PT2H
          description: Minimum time interval separating distinct cycles.
          format: duration
          title: Cycle Gap
          type: string
      - description: Sleep stages to include. Defaults to all stages.
        in: query
        name: stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to include. Defaults to all stages.
          title: Stages
      - description: Sleep stages to consider as gaps in sleep cycles.
        in: query
        name: gap_stages
        required: false
        schema:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Sleep stages to consider as gaps in sleep cycles.
          title: Gap Stages
      - description: 'Whether to merge overlapping stages based on priority and start time: stage 0 (in bed) has lower priority than other stages; stage 2 (unknown sleep stage) has lower priority than other stages except 0; then stages with later start times take precedece.'
        in: query
        name: merge_overlapping
        required: false
        schema:
          default: true
          description: 'Whether to merge overlapping stages based on priority and start time: stage 0 (in bed) has lower priority than other stages; stage 2 (unknown sleep stage) has lower priority than other stages except 0; then stages with later start times take precedece.'
          title: Merge Overlapping
          type: boolean
      - description: Whether to merge contiguous samples with the same sleep stage into one continues stage.
        in: query
        name: merge_contiguous
        required: false
        schema:
          default: true
          description: Whether to merge contiguous samples with the same sleep stage into one continues stage.
          title: Merge Contiguous
          type: boolean
      - description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
        in: query
        name: clip_to_range
        required: false
        schema:
          default: true
          description: Whether to clip the data to the requested date range. This is always done when requesting data for a user other than the authenticated user.
          title: Clip To Range
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Return sleep stages derived from raw fulcra metric samples
      tags:
      - Sleep
components:
  schemas:
    OutputMethod:
      enum:
      - ndjson
      - jstable
      - jscolumns
      - arrow
      - arrowraw
      - parquet
      - csv
      - quotecsv
      title: OutputMethod
      type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    TimeSeriesCalculation:
      description: 'The descriptive statistics calculations that are available on certain

        time-series calls.'
      enum:
      - max
      - min
      - delta
      - mean
      - uniques
      - allpoints
      - rollingmean
      - mode
      title: TimeSeriesCalculation
      type: string
    Mode:
      enum:
      - start
      - end
      - split
      title: Mode
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    AggregateFunction:
      enum:
      - sum
      - avg
      - min
      - max
      title: AggregateFunction
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT