openapi: 3.0.3
info:
  title: Fitbit Devices API
  description: |
    Retrieve information about the user's paired Fitbit devices including
    battery level, last sync time, firmware version, device version (model),
    and manage alarms scheduled on tracker devices.
  version: '1'
  contact:
    name: Fitbit Developer
    url: https://dev.fitbit.com/build/reference/web-api/devices/
servers:
- url: https://api.fitbit.com
security:
- OAuth2:
  - settings
paths:
  /1/user/{user-id}/devices.json:
    get:
      summary: Get Devices
      description: Returns a list of the Fitbit devices connected to a user's account.
      operationId: getDevices
      parameters:
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of devices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
  /1/user/{user-id}/devices/tracker/{tracker-id}/alarms.json:
    get:
      summary: Get Alarms
      description: Returns alarms for a device.
      operationId: getAlarms
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: tracker-id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of alarms.
    post:
      summary: Add Alarm
      description: Adds the alarm settings to a given device.
      operationId: addAlarm
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: tracker-id
        in: path
        required: true
        schema:
          type: string
      - name: time
        in: query
        required: true
        schema:
          type: string
      - name: enabled
        in: query
        required: true
        schema:
          type: boolean
      - name: recurring
        in: query
        required: true
        schema:
          type: boolean
      - name: weekDays
        in: query
        schema:
          type: string
      responses:
        '201':
          description: Alarm created.
  /1/user/{user-id}/devices/tracker/{tracker-id}/alarms/{alarm-id}.json:
    delete:
      summary: Delete Alarm
      description: Deletes a specific alarm entry for the given tracker.
      operationId: deleteAlarm
      parameters:
      - $ref: '#/components/parameters/UserId'
      - name: tracker-id
        in: path
        required: true
        schema:
          type: string
      - name: alarm-id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Alarm deleted.
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:
            settings: Device settings
  schemas:
    Device:
      type: object
      properties:
        battery:
          type: string
          enum: [High, Medium, Low, Empty]
        batteryLevel:
          type: integer
        deviceVersion:
          type: string
        features:
          type: array
          items:
            type: string
        id:
          type: string
        lastSyncTime:
          type: string
          format: date-time
        mac:
          type: string
        type:
          type: string
          enum: [TRACKER, SCALE]