openapi: 3.0.3
info:
  title: Fitbit Heart Rate API
  description: |
    Read user heart rate data from Fitbit. Provides resting heart rate, heart
    rate zones, and time-series heart rate measurements at day, week, month, and
    year granularity. Intraday endpoints expose 1-minute or 1-second detail-level
    series and require explicit Intraday access approval from Fitbit/Google.
  version: '1'
  contact:
    name: Fitbit Developer
    url: https://dev.fitbit.com/build/reference/web-api/heartrate-timeseries/
servers:
- url: https://api.fitbit.com
security:
- OAuth2:
  - heartrate
paths:
  /1/user/{user-id}/activities/heart/date/{date}/{period}.json:
    get:
      summary: Get Heart Rate Time Series By Date
      description: Retrieves a user's heart rate time series for the given date and period.
      operationId: getHeartRateTimeSeriesByDate
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: date
        in: path
        required: true
        schema:
          type: string
      - name: period
        in: path
        required: true
        schema:
          type: string
          enum: [1d, 7d, 30d, 1w, 1m]
      responses:
        '200':
          description: Heart rate time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartRateTimeSeries'
  /1/user/{user-id}/activities/heart/date/{base-date}/{end-date}.json:
    get:
      summary: Get Heart Rate Time Series By Date Range
      description: Retrieves a user's heart rate time series for the given date range.
      operationId: getHeartRateTimeSeriesByDateRange
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: base-date
        in: path
        required: true
        schema:
          type: string
      - name: end-date
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Heart rate time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartRateTimeSeries'
  /1/user/{user-id}/activities/heart/date/{date}/1d/{detail-level}.json:
    get:
      summary: Get Heart Rate Intraday Time Series
      description: Retrieves the user's heart rate intraday time series at the requested detail level (1sec, 1min, 5min, or 15min). Requires Intraday access.
      operationId: getHeartRateIntradayTimeSeries
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: date
        in: path
        required: true
        schema:
          type: string
      - name: detail-level
        in: path
        required: true
        schema:
          type: string
          enum: [1sec, 1min, 5min, 15min]
      responses:
        '200':
          description: Heart rate intraday data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartRateIntraday'
components:
  parameters:
    UserId:
      name: user-id
      in: path
      required: true
      schema:
        type: string
        default: '-'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.fitbit.com/oauth2/authorize
          tokenUrl: https://api.fitbit.com/oauth2/token
          scopes:
            heartrate: Heart rate data
  schemas:
    HeartRateTimeSeries:
      type: object
      properties:
        activities-heart:
          type: array
          items:
            type: object
            properties:
              dateTime:
                type: string
                format: date
              value:
                type: object
                properties:
                  customHeartRateZones:
                    type: array
                    items:
                      $ref: '#/components/schemas/HeartRateZone'
                  heartRateZones:
                    type: array
                    items:
                      $ref: '#/components/schemas/HeartRateZone'
                  restingHeartRate:
                    type: integer
    HeartRateZone:
      type: object
      properties:
        caloriesOut:
          type: number
        max:
          type: integer
        min:
          type: integer
        minutes:
          type: integer
        name:
          type: string
    HeartRateIntraday:
      type: object
      properties:
        activities-heart-intraday:
          type: object
          properties:
            dataset:
              type: array
              items:
                type: object
                properties:
                  time:
                    type: string
                  value:
                    type: integer
            datasetInterval:
              type: integer
            datasetType:
              type: string