openapi: 3.1.0
info:
title: FranklinWH 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). The portal ships its complete operation catalogue - paths,
HTTP methods, parameter names, locations, types, requirement flags and value notes - as a static, publicly retrievable
JavaScript module; this OpenAPI document is a faithful format conversion of that catalogue. Nothing has been added that
the portal does not publish. Response payload schemas are NOT published by the portal, so only the observed response envelope
is modelled here.
The API covers site and device inventory, telemetry and energy data, warnings and backup events, time-of-use profiles,
smart-circuit and grid-event control, aPower battery start/stop, device grouping and an operation audit log, plus a Sunrun-specific
namespace (`/api-sunrun/`).
Authentication: POST /api-common/tokenizer with a `cp` / `ck` credential pair returns a token that is sent on every other
operation in the `Authorization` header.
Base URL: the only base URL FranklinWH publishes publicly is the free test environment, https://test-api.franklinwh.com.
The production base URL is issued to authorised partners during onboarding and is not published.'
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`).
tags:
- name: Authentication
description: Token issuance for the FranklinWH partner API.
- name: Sites
description: Site records — query, list, modify and delete.
- name: Devices
description: Device inventory, device information and device parameters.
- name: Device Data
description: Power, energy, telemetry, inventory and historical load data.
- name: Warnings and Events
description: Historical device warnings and backup (outage) events.
- name: System Settings
description: Time-of-use profiles, aPower switch control and smart-circuit settings.
- name: Grid Events
description: Grid-event scheduling and query.
- name: Groups
description: Device grouping and bulk settings applied by group.
- name: Modification Records
description: Audit log of setting changes.
- name: Sunrun
description: Sunrun-specific operations on the /api-sunrun namespace.
- name: Sunrun Sites
description: Sunrun site asset inventory.
- name: Sunrun System Setup
description: Sunrun energy-management and aPower switch control.
paths:
/api-common/tokenizer:
post:
tags:
- Authentication
summary: Update Token
operationId: tokenizer
description: Fetch token by using CK CP
security: []
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/querySiteInfo:
get:
tags:
- Sites
summary: Query Site Information
operationId: querySiteInfo
description: Query site information according to the site ID
parameters:
- name: siteId
in: query
required: true
schema:
type: integer
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/querySiteList:
get:
tags:
- Sites
summary: Query Site List
operationId: querySiteList
description: Get all site information, or the site information of its installers
parameters:
- name: installerId
in: query
required: false
schema:
type: integer
description: Installer ID
- name: siteName
in: query
required: false
schema:
type: string
description: Site name
- name: userAccount
in: query
required: false
schema:
type: string
description: User account
- name: deviceId
in: query
required: false
schema:
type: string
description: Device ID
- 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'
/api-common/modifySite:
post:
tags:
- Sites
summary: Modify or Delete a Site
operationId: modifySite
description: Modify or delete a site
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
opt:
type: integer
description: Operation type. 1:Modify, 2:Delete
siteId:
type: integer
description: Site ID
siteName:
type: string
description: Site name
longitude:
type: string
description: Longitude of the site
latitude:
type: string
description: Latitude of the site
address:
type: string
description: Site address
postCode:
type: string
description: Zip code
installerId:
type: integer
description: Installer ID
required:
- opt
- siteId
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/queryDeviceList:
get:
tags:
- Devices
summary: Query Device List
operationId: queryDeviceList
description: Get device list information
parameters:
- name: current
in: query
required: false
schema:
type: integer
description: Current page. Defaults to the first page if not posted
- name: pageSize
in: query
required: false
schema:
type: integer
description: Display quantity per page. The default number is 20 if not posted. Maximum is 50
- name: installerId
in: query
required: false
schema:
type: integer
description: Installer ID
- name: deviceId
in: query
required: false
schema:
type: string
description: Device ID
- name: groupId
in: query
required: false
schema:
type: integer
description: Group ID
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/editDeviceInfo:
post:
tags:
- Devices
summary: Edit Deivce Information
operationId: editDeviceInfo
description: Edit Deivce Information
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
siteId:
type: integer
description: Site ID
longitude:
type: string
description: Longitude of the device
latitude:
type: string
description: Latitude of the device
address:
type: string
description: Installation address
installerId:
type: integer
description: Installer id
required:
- deviceId
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/queryDeviceParameters:
get:
tags:
- Devices
summary: Query device parameters
operationId: queryDeviceParameters
description: Query device parameters
parameters:
- name: deviceId
in: query
required: true
schema:
type: string
description: Device id
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/queryDeviceRunningStatus:
get:
tags:
- Devices
summary: Query device running status
operationId: queryDeviceRunningStatus
description: Query device running status
parameters:
- name: deviceId
in: query
required: true
schema:
type: string
description: Device id
- name: type
in: query
required: true
schema:
type: integer
description: 'Query type. 1: Running data (The latest data of the day) 2: Daily data (All 5 minutes data on the selected
day, including today or history)'
- name: queryDate
in: query
required: false
schema:
type: string
description: Specific date. Required when the query type is 2
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/queryPowerData:
get:
tags:
- Device Data
summary: Query Power Data
operationId: queryPowerData
description: Get the latest data of the day or query all data on a specific date
parameters:
- name: deviceId
in: query
required: true
schema:
type: string
description: Device id
- name: type
in: query
required: true
schema:
type: integer
description: 'Query type. 1: Running data (The latest data of the day) 2: Daily data (All 5 minutes data on the selected
day, including today or history)'
- name: queryDate
in: query
required: false
schema:
type: string
description: Specific date. Only required when the query type is 2
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/getMaxPowerData:
post:
tags:
- Device Data
summary: Query Maximum Power Data
operationId: getMaxPowerData
description: Query the maximum power within defined periods
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
type:
type: integer
description: 'Query type: 1: Day, 2：Week, 3:Month, 4:Year, 5:Total'
queryDate:
type: integer
description: 'Date. When type is 2, calculate the week boundaries based on the selected date Required: When
type is 1-4; Not required: when type is 5'
required:
- deviceId
- type
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/queryEnergyData:
post:
tags:
- Device Data
summary: Query Energy Data
operationId: queryEnergyData
description: Get the latest data or all energy data within defined periods
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
type:
type: integer
description: 'Query type: 1: Day, 2:Week, 3:Month , 4:Year, 5:Total. Day: Data is returned at a time of
5 minutes. Week: Data is returned at a time for each day of the week. Month: Data is returned at a time
for each day of the month.Year: Data is returned at a time for each month of the year. Total: Data is
returned at a time for each year of the lifetime'
queryDate:
type: string
description: 'Date. When type is 2, calculate the week boundaries based on the selected date Required: When
type is 1-4; Not required: when type is 5'
required:
- deviceId
- type
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/queryPowerSourceDetails:
post:
tags:
- Device Data
summary: Query Power Source Details
operationId: queryPowerSourceDetails
description: Get the latest data about FHP, grid, and solar, or the data on a specific date
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device ID
type:
type: integer
description: 'Query type. 1: Running data (The latest data of the day) 2: Daily data (All 15 minutes data
on the selected day, including today or history)'
queryDate:
type: string
description: Query date. Only required when the query type is 2
required:
- deviceId
- type
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/queryDeviceDataPool:
get:
tags:
- Device Data
summary: Query Telemetry Grouping
operationId: queryDeviceDataPool
description: Query Telemetry Grouping
parameters:
- name: deviceId
in: query
required: false
schema:
type: string
description: Device ID. deviceId and siteId can not both null
- name: siteId
in: query
required: false
schema:
type: integer
description: SiteID. deviceId and siteId can not both null
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/queryInventory:
get:
tags:
- Device Data
summary: Query Inventory
operationId: queryInventory
description: Query Inventory
parameters:
- name: deviceId
in: query
required: false
schema:
type: string
description: Device id
- name: siteId
in: query
required: false
schema:
type: integer
description: Site ID
- name: siteName
in: query
required: false
schema:
type: string
description: Site name. Need to be unique
- name: current
in: query
required: false
schema:
type: integer
description: Current Page. Defaults to the first page if not posted
- name: pageSize
in: query
required: false
schema:
type: integer
description: Display quantity per page. 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'
/api-common/historyDataLoad:
get:
tags:
- Device Data
summary: Query Historical Data Load
operationId: historyDataLoad
description: Query Historical Data Load, this API offers total 7 days running history data ( 5 min. Period )
parameters:
- name: siteName
in: query
required: false
schema:
type: string
description: Site Name. siteNameand siteId can not both null
- name: siteId
in: query
required: false
schema:
type: integer
description: Site ID. siteNameand siteId can not both null
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/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'
/api-common/setTouProfile:
post:
tags:
- System Settings
summary: Set TOU Profile
operationId: setTouProfile
description: Set energy TOU profile
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
touId:
type: integer
description: TOU profile ID
season:
type: array
items:
type: object
description: TOU profile season
required:
- deviceId
- touId
- season
example:
deviceId: 10080008B00A22150090
touId: 10688
season:
- month: 5,6,7,8,9,10
dayType: 1
time:
- startTime: 00:00
endTime: 08:00
waveType: 0
schedule: 8
- startTime: 08:00
endTime: '21:00'
waveType: 1
schedule: 2
- startTime: '21:00'
endTime: 08:00
waveType: 2
schedule: 1
- month: 5,6,7,8,9,10
dayType: 1
time:
- startTime: 00:00
endTime: 08:00
waveType: 0
schedule: 8
- startTime: 08:00
endTime: '21:00'
waveType: 1
schedule: 2
- startTime: '21:00'
endTime: 08:00
waveType: 2
schedule: 1
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/queryTouProfile:
get:
tags:
- System Settings
summary: Query TOU Profile
operationId: queryTouProfile
description: Query energy TOU profile
parameters:
- name: deviceId
in: query
required: true
schema:
type: string
description: Device id
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/setSwitchParam:
post:
tags:
- System Settings
summary: Set aPower Switch
operationId: setSwitchParam
description: Set aPower Switch
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
cmd:
type: integer
description: 'Type. 1 : Start up, 2 : Shut down'
required:
- deviceId
- cmd
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/queryApowerSwitchStatus:
get:
tags:
- System Settings
summary: Query aPower Switch Status
operationId: queryApowerSwitchStatus
description: Query aPower Switch Status
parameters:
- name: deviceId
in: query
required: true
schema:
type: string
description: Device id
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/setSmartCircuits:
post:
tags:
- System Settings
summary: Set Smart Circuits
operationId: setSmartCircuits
description: Set smart circuits
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
deviceId:
type: string
description: Device id
swMerge:
type: integer
description: 'Circuits Merge. 0: Separated 1 : Merged If set to 1, It represents the merging of circuit
1 and circuit 2, and all the value set by sw2 will be invalid'
sw1Name:
type: string
description: Circuit 1 naming
sw1MsgType:
type: inte
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/franklin-whole-home/refs/heads/main/openapi/franklin-whole-home-openapi.yml