openapi: 3.0.3
info:
  title: Sense Client API
  description: >-
    The Sense Client REST API provides access to historical trend data and
    account information for Sense home energy monitors. Authenticated users
    can retrieve aggregated energy consumption and solar production statistics
    across configurable time scales including day, week, month, year, and
    billing cycle. The API returns device-level disaggregation data showing
    individual appliance consumption, grid exchange metrics, and monitor
    health information.
  version: 1.0.0
  contact:
    name: Sense Support
    url: https://help.sense.com
servers:
  - url: https://api.sense.com/apiservice/api/v1
    description: Sense REST API
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: Authenticate and manage sessions
  - name: Monitors
    description: Monitor overview, status, and device detection
  - name: Devices
    description: Device-level energy data and device information
  - name: History
    description: Historical energy usage and solar production data
  - name: Users
    description: User-level timeline and usage data
paths:
  /authenticate:
    post:
      operationId: authenticate
      summary: Authenticate with email and password
      description: >-
        Authenticate with a Sense account using email and password. Returns an
        access token, user ID, refresh token, and a list of associated monitors.
        If MFA is enabled, a 401 with an mfa_token is returned requiring a
        follow-up call to /authenticate/mfa.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  description: The user's Sense account email address
                  example: user@example.com
                password:
                  type: string
                  format: password
                  description: The user's Sense account password
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Authentication failed or MFA required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MFARequired'
  /authenticate/mfa:
    post:
      operationId: validateMfa
      summary: Validate MFA code
      description: >-
        Validate a Time-based One-Time Password (TOTP) code after initial
        authentication returned a 401 with an mfa_token. On success returns
        full auth credentials identical to the /authenticate response.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - totp
                - mfa_token
                - client_time
              properties:
                totp:
                  type: string
                  description: The 6-digit TOTP code from the authenticator app
                  example: '123456'
                mfa_token:
                  type: string
                  description: The mfa_token returned from the initial authenticate call
                client_time:
                  type: string
                  format: date-time
                  description: Current UTC time in ISO 8601 format
                  example: '2026-06-13T12:00:00Z'
      responses:
        '200':
          description: MFA validated, authentication complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid MFA code
  /renew:
    post:
      operationId: renewAuth
      summary: Renew access token using refresh token
      description: >-
        Exchange a refresh token for a new access token. Call this when the
        current access token is expired (401 response from any authenticated
        endpoint).
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - user_id
                - refresh_token
              properties:
                user_id:
                  type: string
                  description: The user's Sense user ID from the original auth response
                  example: '123456'
                refresh_token:
                  type: string
                  description: The refresh token from the original auth response
      responses:
        '200':
          description: Token renewed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Refresh token invalid or expired
  /logout:
    get:
      operationId: logout
      summary: Log out and invalidate the current session
      description: Invalidates the current access token and ends the session.
      tags:
        - Authentication
      responses:
        '200':
          description: Successfully logged out
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/overview:
    get:
      operationId: getMonitorOverview
      summary: Get monitor overview
      description: >-
        Retrieve overview information for a Sense monitor, including the
        monitor object with solar configuration flags, firmware version, and
        associated account details.
      tags:
        - Monitors
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: Monitor overview data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorOverviewResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Monitor not found
  /app/monitors/{monitor_id}/status:
    get:
      operationId: getMonitorStatus
      summary: Get monitor and device detection status
      description: >-
        Retrieve current status of the monitor including hardware health,
        network connectivity, and device detection progress. Also returns
        the current firmware version installed on the monitor.
      tags:
        - Monitors
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: Monitor status data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorStatusResponse'
        '401':
          description: Unauthorized
        '404':
          description: Monitor not found
  /app/monitors/{monitor_id}/devices:
    get:
      operationId: getDiscoveredDevices
      summary: List discovered devices
      description: >-
        Retrieve the list of devices that Sense has identified through
        machine-learning disaggregation. Each device entry includes the
        device ID, name, icon identifier, and current on/off status.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: List of discovered devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/devices/overview:
    get:
      operationId: getDevicesOverview
      summary: Get devices overview
      description: >-
        Retrieve an overview of all detected devices including their current
        power consumption and identification status. Used by the async client
        to fetch device lists.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: Device overview data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesOverviewResponse'
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/devices/always_on:
    get:
      operationId: getAlwaysOnInfo
      summary: Get always-on device info
      description: >-
        Retrieve information about always-on power consumption — devices and
        loads that draw power continuously. This mirrors the always-on section
        in the Sense web application.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: Always-on device information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlwaysOnResponse'
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/devices/{device_id}:
    get:
      operationId: getDeviceInfo
      summary: Get specific device information
      description: >-
        Retrieve detailed information about a specific detected device,
        including its name, icon, current power, and energy history.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: The device ID returned from the devices list
          example: abc123def456
      responses:
        '200':
          description: Device detail data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetail'
        '401':
          description: Unauthorized
        '404':
          description: Device not found
  /monitors/{monitor_id}/devices:
    get:
      operationId: getRawDeviceData
      summary: Get raw device data
      description: >-
        Retrieve raw device data from the legacy (non-app) endpoint. Returns
        the complete device list with all properties.
      tags:
        - Devices
      parameters:
        - $ref: '#/components/parameters/MonitorId'
      responses:
        '200':
          description: Raw device list data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/history/usage:
    get:
      operationId: getUsageHistory
      summary: Get historical energy usage
      description: >-
        Retrieve historical energy consumption data aggregated at the
        specified scale (DAY, WEEK, MONTH, YEAR, or CYCLE). Returns total
        usage in kWh with a device-level breakdown showing individual
        appliance consumption.
      tags:
        - History
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: scale
          in: query
          required: true
          schema:
            type: string
            enum:
              - DAY
              - WEEK
              - MONTH
              - YEAR
              - CYCLE
          description: The time scale for aggregation
          example: DAY
        - name: start
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date/time in ISO 8601 format (UTC)
          example: '2026-06-13T00:00:00'
      responses:
        '200':
          description: Historical usage data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageHistoryResponse'
        '401':
          description: Unauthorized
  /app/monitors/{monitor_id}/history/usage/solar:
    get:
      operationId: getSolarHistory
      summary: Get historical solar production data
      description: >-
        Retrieve historical solar production data for monitors with solar
        configured. Returns production totals, grid exchange (from_grid_kwh,
        to_grid_kwh), net production, and solar percentage of consumption
        for the requested scale and start date.
      tags:
        - History
      parameters:
        - $ref: '#/components/parameters/MonitorId'
        - name: scale
          in: query
          required: true
          schema:
            type: string
            enum:
              - DAY
              - WEEK
              - MONTH
              - YEAR
              - CYCLE
          description: The time scale for aggregation
          example: DAY
        - name: start
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Start date/time in ISO 8601 format (UTC)
          example: '2026-06-13T00:00:00'
      responses:
        '200':
          description: Historical solar data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolarHistoryResponse'
        '401':
          description: Unauthorized
  /app/{monitor_id}/realtime_update:
    get:
      operationId: getRealtimeUpdate
      summary: Get a single realtime update
      description: >-
        Retrieve the current real-time power snapshot for a monitor without
        opening a WebSocket connection. Supported on monitors running firmware
        version 1.64 or later. Returns the same payload structure as the
        WebSocket realtime_update message.
      tags:
        - Monitors
      parameters:
        - name: monitor_id
          in: path
          required: true
          schema:
            type: string
          description: The monitor's unique ID
          example: '12345'
      responses:
        '200':
          description: Realtime update snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RealtimePayload'
        '401':
          description: Unauthorized
  /users/{user_id}/timeline:
    get:
      operationId: getUserTimeline
      summary: Get user usage timeline
      description: >-
        Retrieve a timeline of usage events and device activity for the
        authenticated user. Supports pagination and filtering by device.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
          description: The user's Sense user ID
          example: '654321'
        - name: n_items
          in: query
          schema:
            type: integer
            default: 30
          description: Number of timeline items to return
          example: 30
        - name: device_id
          in: query
          schema:
            type: string
          description: Filter results to a specific device ID
        - name: prior_to_item
          in: query
          schema:
            type: string
            format: date-time
          description: Return items prior to this date/time (YYYY-MM-DDTHH:MM:SS.mmmZ)
        - name: rollup
          in: query
          schema:
            type: string
          description: Optional rollup grouping parameter
      responses:
        '200':
          description: User timeline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelineResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token obtained from the /authenticate or /renew endpoints.
        Include as "Authorization: bearer <access_token>" header.
  parameters:
    MonitorId:
      name: monitor_id
      in: path
      required: true
      schema:
        type: string
      description: The Sense monitor's unique numeric ID
      example: '12345'
  schemas:
    AuthResponse:
      type: object
      description: Successful authentication response containing credentials and monitor list
      properties:
        access_token:
          type: string
          description: Bearer token for authenticating subsequent API calls
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        user_id:
          type: string
          description: Unique identifier for the authenticated user
          example: '654321'
        refresh_token:
          type: string
          description: Long-lived token for renewing the access token
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        monitors:
          type: array
          description: List of Sense monitors associated with the account
          items:
            $ref: '#/components/schemas/MonitorSummary'
    MFARequired:
      type: object
      description: Response when MFA code is required to complete authentication
      properties:
        mfa_token:
          type: string
          description: Token to pass to the /authenticate/mfa endpoint
        error_reason:
          type: string
          description: Human-readable explanation of why MFA is required
          example: MFA required
    MonitorSummary:
      type: object
      description: Summary of a Sense monitor returned in authentication responses
      properties:
        id:
          type: string
          description: Unique monitor ID
          example: '12345'
        serial_number:
          type: string
          description: Physical device serial number
          example: SN1234567890
        time_zone:
          type: string
          description: IANA time zone identifier for the monitor location
          example: America/New_York
        solar_configured:
          type: boolean
          description: Whether solar monitoring is configured for this monitor
          example: false
    MonitorOverviewResponse:
      type: object
      description: Full monitor overview including monitor details and account info
      properties:
        monitor_overview:
          type: object
          properties:
            monitor:
              $ref: '#/components/schemas/MonitorDetail'
    MonitorDetail:
      type: object
      description: Detailed monitor information
      properties:
        id:
          type: string
          description: Unique monitor ID
          example: '12345'
        serial_number:
          type: string
          description: Physical device serial number
        time_zone:
          type: string
          description: IANA time zone for this monitor
          example: America/Chicago
        solar_configured:
          type: boolean
          description: Whether solar production monitoring is active
          example: false
        version:
          type: string
          description: Currently installed firmware version
          example: '1.65.3490-g0f9f5a3'
        signal_check_capable:
          type: boolean
          description: Whether the monitor supports signal quality checks
    MonitorStatusResponse:
      type: object
      description: Monitor status including health and device detection progress
      properties:
        monitor_info:
          type: object
          properties:
            version:
              type: string
              description: Firmware version string
              example: '1.65.3490-g0f9f5a3'
            wifi_strength:
              type: integer
              description: WiFi signal strength in dBm
              example: -55
            ndevices_found:
              type: integer
              description: Number of devices detected so far
              example: 12
            detection_running:
              type: boolean
              description: Whether device detection is actively running
              example: true
    Device:
      type: object
      description: A machine-learning detected electrical device
      properties:
        id:
          type: string
          description: Unique identifier for the device
          example: abc123def456
        name:
          type: string
          description: Human-readable device name assigned by Sense or the user
          example: Refrigerator
        icon:
          type: string
          description: Icon identifier for displaying in the app
          example: fridge
        is_on:
          type: boolean
          description: Whether the device is currently drawing power
          example: true
        power_w:
          type: number
          format: float
          description: Current power consumption in watts
          example: 150.5
        tags:
          type: object
          additionalProperties: true
          description: Additional metadata tags for the device
    DevicesOverviewResponse:
      type: object
      description: Overview of all detected devices
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        total_count:
          type: integer
          description: Total number of detected devices
    AlwaysOnResponse:
      type: object
      description: Always-on load information
      properties:
        always_on:
          type: number
          format: float
          description: Total always-on wattage
          example: 312.4
        components:
          type: array
          description: Individual always-on components
          items:
            type: object
            properties:
              name:
                type: string
              watts:
                type: number
                format: float
    DeviceDetail:
      type: object
      description: Detailed information for a specific device
      allOf:
        - $ref: '#/components/schemas/Device'
        - type: object
          properties:
            energy_kwh:
              type: object
              description: Energy consumption by time scale
              properties:
                DAY:
                  type: number
                  format: float
                  description: Daily energy in kWh
                WEEK:
                  type: number
                  format: float
                  description: Weekly energy in kWh
                MONTH:
                  type: number
                  format: float
                  description: Monthly energy in kWh
                YEAR:
                  type: number
                  format: float
                  description: Annual energy in kWh
    UsageHistoryResponse:
      type: object
      description: Historical energy consumption data
      properties:
        start:
          type: string
          format: date-time
          description: Start of the reported period
          example: '2026-06-13T00:00:00Z'
        consumption:
          type: object
          properties:
            usage_total_kwh:
              type: number
              format: float
              description: Total energy consumed in kWh for the period
              example: 18.42
        device_breakdown:
          type: array
          description: Per-device energy breakdown
          items:
            type: object
            properties:
              id:
                type: string
                description: Device ID
              name:
                type: string
                description: Device name
              icon:
                type: string
                description: Device icon identifier
              consumption:
                type: object
                properties:
                  usage_total_kwh:
                    type: number
                    format: float
                    description: Device's total energy consumption in kWh
    SolarHistoryResponse:
      type: object
      description: Historical solar production and grid exchange data
      properties:
        total:
          type: object
          properties:
            production_kwh:
              type: number
              format: float
              description: Total solar energy produced in kWh
              example: 12.75
            from_grid_kwh:
              type: number
              format: float
              description: Energy imported from the grid in kWh
              example: 5.67
            to_grid_kwh:
              type: number
              format: float
              description: Excess solar energy exported to the grid in kWh
              example: 2.31
            net_kwh:
              type: number
              format: float
              description: Net energy (production minus consumption) in kWh
              example: 7.08
            solar_percentage:
              type: number
              format: float
              description: Percentage of consumption covered by solar (0-100)
              example: 68.5
    RealtimePayload:
      type: object
      description: Real-time power snapshot from the monitor
      properties:
        w:
          type: number
          format: float
          description: Current whole-home power consumption in watts
          example: 1234.5
        solar_w:
          type: number
          format: float
          description: Current solar production in watts (0 if no solar)
          example: 850.0
        grid_w:
          type: number
          format: float
          description: Net grid exchange in watts (positive=importing, negative=exporting)
          example: 384.5
        hz:
          type: number
          format: float
          description: AC frequency in Hz
          example: 60.01
        voltage:
          type: array
          items:
            type: number
            format: float
          description: Voltage readings per leg in volts
          example:
            - 121.2
            - 120.8
        devices:
          type: array
          description: Currently active detected devices
          items:
            type: object
            properties:
              id:
                type: string
                description: Device ID
              name:
                type: string
                description: Device name
              icon:
                type: string
                description: Device icon
              w:
                type: number
                format: float
                description: Current device power in watts
    TimelineResponse:
      type: object
      description: User activity timeline with device events
      properties:
        items:
          type: array
          description: Timeline event items
          items:
            type: object
            properties:
              type:
                type: string
                description: Event type (e.g. DeviceWentOn, DeviceWentOff)
                example: DeviceWentOn
              time:
                type: string
                format: date-time
                description: When the event occurred
              device_id:
                type: string
                description: Device involved in the event
              device_name:
                type: string
                description: Name of the device
              user_device_type:
                type: string
                description: Device category
        total_items:
          type: integer
          description: Total number of items matching the filter