Franklin Whole Home Warnings and Events API

openapi: 3.2.0
info:
  title: FranklinWH Warnings and Events API
  version: '1.0'
  summary: Partner API for the FranklinWH (Franklin Whole Home) residential energy storage platform.
  description: Machine-readable rendering of the FranklinWH partner API as published by FranklinWH's own API portal at https://api.franklinwh.com/ (portal title `FWH-API-Service`, author `FWH`, version 1.0).
  contact:
    name: FranklinWH Support
    email: service@franklinwh.com
    url: https://www.franklinwh.com/support/contact/
  x-provenance:
    method: derived
    source: https://api.franklinwh.com/js/apiList-eQeWKe2I.js
    source_portal: https://api.franklinwh.com/
    derived: '2026-08-16'
    note: Converted from the FranklinWH API portal's own published operation catalogue. Operations, parameters and request examples are verbatim from that catalogue; no operation, parameter or schema was invented.
servers:
- url: https://test-api.franklinwh.com
  description: Free test environment - the only base URL FranklinWH publishes publicly (portal `host` / `basePath`).
security:
- AuthorizationToken: []
tags:
- name: Warnings and Events
  description: Historical device warnings and backup (outage) events.
paths:
  /api-common/queryDeviceHistoricalWarning:
    get:
      tags:
      - Warnings and Events
      summary: Query Historical Warning
      operationId: queryDeviceHistoricalWarning
      description: Query historical warning data within a defined period, the time span should not exceed 1 month
      parameters:
      - name: deviceId
        in: query
        required: true
        schema:
          type: string
        description: Device id
      - name: queryStartTime
        in: query
        required: true
        schema:
          type: string
        description: Query start time. Device time
      - name: queryEndTime
        in: query
        required: true
        schema:
          type: string
        description: Query end time. Device time
      responses:
        '200':
          description: Envelope response. Non-zero `code` values (401 wrong token, 403 missing token or token param) are returned inside the envelope with HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiEnvelope'
        '404':
          description: Unknown path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
  /api-common/queryBackupEvents:
    get:
      tags:
      - Warnings and Events
      summary: Query Backup Events
      operationId: queryBackupEvents
      description: Query backup events data within a defined period, the time span should not exceed 1 month
      parameters:
      - name: deviceId
        in: query
        required: true
        schema:
          type: string
        description: Device id
      - name: queryStartTime
        in: query
        required: true
        schema:
          type: string
        description: Query the start time of the start time. Device time
      - name: queryEndTime
        in: query
        required: true
        schema:
          type: string
        description: Query end time of the start time. Device time
      - name: current
        in: query
        required: false
        schema:
          type: integer
        description: Current page. Start the query from page 1 and upload the page number that need to be queried. Defaults to the first page if not posted
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
        description: Display quantity per page. Number of data returned by the current page when queried. The default number is 20 if not posted. Maximum is 50
      responses:
        '200':
          description: Envelope response. Non-zero `code` values (401 wrong token, 403 missing token or token param) are returned inside the envelope with HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiEnvelope'
        '404':
          description: Unknown path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
components:
  schemas:
    NotFoundError:
      type: object
      description: Framework 404 body returned for unknown paths.
      properties:
        timestamp:
          type: string
          format: date-time
        path:
          type: string
        status:
          type: integer
        error:
          type: string
        message:
          type:
          - string
          - 'null'
        requestId:
          type: string
      examples:
      - timestamp: '2026-08-16T17:23:07.914+00:00'
        path: /
        status: 404
        error: Not Found
        message: null
        requestId: 1748b892-1427296
    ApiEnvelope:
      type: object
      description: Response envelope used by every operation. Observed live on https://test-api.franklinwh.com.
      properties:
        code:
          type: integer
          description: Result code. 401 = wrong token, 403 = missing token or token param.
        msg:
          type: string
          description: Human-readable result message.
        data:
          description: Operation payload. FranklinWH does not publish payload schemas; shape varies per operation.
      examples:
      - code: 401
        msg: wrong token
  securitySchemes:
    AuthorizationToken:
      type: apiKey
      in: header
      name: Authorization
      description: Token returned by POST /api-common/tokenizer (exchange of a `cp` / `ck` credential pair).