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: integer description: 'Operation type. 1 : Manual switch 2 : Parameter settings' sw1SocLowSet: type: integer description: 'SOC threshold to shed loads on circuit 1. 0~100；0 : No limit … 100 : Turn off immediately after disconnecting from the grid' sw1Mode: type: integer description: 'Circuit 1 operation. 0 : Manually turn off 1: Manually turn on, 2 :Timing plan' sw1ProLoad: type: integer description: 'Circuit 1 status. 0: Off 1:On' sw1Freq: type: integer description: 'Cycle period of Circuit 1. 0 : Single 1: Daily 2 : Weekly 3: Monthly' sw1TimeEn: type: array items: type: integer description: 'Circuit 1 timing plan. [0, 1] 0: Disabled 1: Enabled' sw1Time: type: array items: type: string description: Circuit 1 time period. ["2021-08-06 09:00/ 2021-08-06 12:00", "2021-08-06 18:00/ 2021-08-06 20:00"] Up to 2 time periods sw2Name: type: string description: Circuit 2 naming. All parameter descriptions refer to sw1 sw2MsgType: type: integer description: Operation type. All parameter descriptions refer to sw1 sw2SocLowSet: type: integer description: SOC threshold to shed loads on circuit 2. All parameter descriptions refer to sw1 sw2Mode: type: integer description: Circuit 2 operation. All parameter descriptions refer to sw1 sw2ProLoad: type: integer description: Circuit 2 status. All parameter descriptions refer to sw1 sw2Freq: type: integer description: Cycle period of Circuit 2. All parameter descriptions refer to sw1 sw2TimeEn: type: integer description: Circuit 2 timing plan. All parameter descriptions refer to sw1 sw2Time: type: array items: type: integer description: Circuit 2 time period. All parameter descriptions refer to sw1 sw3Name: type: string description: Circuit 3 naming. All parameter descriptions refer to sw1 sw3MsgType: type: integer description: Operation type. All parameter descriptions refer to sw1 sw3SocLowSet: type: integer description: SOC threshold to shed loads on circuit 3. All parameter descriptions refer to sw1 sw3Mode: type: integer description: Circuit 3 operation. All parameter descriptions refer to sw1 sw3ProLoad: type: integer description: Circuit 3 status. All parameter descriptions refer to sw1 sw3Freq: type: integer description: Cycle period of Circuit 3. All parameter descriptions refer to sw1 sw3TimeEn: type: integer description: Circuit 3 timing plan. All parameter descriptions refer to sw1 sw3Time: type: array items: type: integer description: Circuit 3 time period. All parameter descriptions refer to sw1 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/querySmartCircuitParameters: get: tags: - System Settings summary: Query Smart Circuit Parameters operationId: querySmartCircuitParameters description: Query smart circuit 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/setGridEvents: post: tags: - Grid Events summary: Set Grid Events operationId: setGridEvents description: Grid event settings requestBody: required: true content: application/json: schema: type: object properties: deviceId: type: string description: Device ID eventList: type: string description: Events list. Json nested field required: - deviceId - eventList example: deviceId: 10080008B00A22150090 eventList: - id: 2 cmd: 1 start: 1669266750 end: 1669273950 power: 4.6 resoc: 50 feedEn: 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/queryGridEvents: get: tags: - Grid Events summary: Query Grid Events operationId: queryGridEvents description: Query Grid Events 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/createGroup: post: tags: - Groups summary: Create Groups operationId: createGroup description: Could create groups parameters: - name: groupId in: query required: false schema: type: integer description: Group Id. groupId or groupName can not both null - name: groupName in: query required: false schema: type: string description: Group Name. groupId or groupName can not both null - name: groupComment in: query required: false schema: type: string description: Group notes - name: installerId in: query required: false schema: type: integer description: Installer 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/modifyGroups: post: tags: - Groups summary: Modify Groups operationId: modifyGroups description: Modify group parameters parameters: - name: groupId in: query required: false schema: type: integer description: Group Id. groupId or groupName can not both null - name: orgGroupName in: query required: false schema: type: string description: Origin Group Name. groupId or orgGroupName can not both null - name: groupComment in: query required: false schema: type: string description: Group notes - name: groupNameNew in: query required: false schema: type: string description: Group name - name: installerId in: query required: false schema: type: integer description: Installer 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/manageGroupsDevices: post: tags: - Groups summary: Manage Devices in a Group operationId: manageGroupsDevices description: Add or delete devices in a group requestBody: required: true content: application/json: schema: type: object properties: groupId: type: integer description: Group Id. groupId or groupName can not both null groupName: type: string description: Group name. groupId or groupName can not both null opt: type: integer description: 'Operating type. 1: Add, 2 : delete' deviceIds: type: array items: type: string description: Device ID list required: - opt - deviceIds 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/setDevicesByGroup: post: tags: - Groups summary: Set Devices by Group operationId: setDevicesByGroup description: Set devices by group requestBody: required: true content: application/json: schema: type: object properties: groupId: type: integer description: Group Id. groupId or groupName can not both null groupName: type: string description: Group name. groupId or groupName can not both null setType: type: integer description: 'Setting types. 1: Edit Device Information 2: Set Energy Management Parameters 3: Set TOU parameters 4: Set aPower Switch 5: Set Smart Circuits 6: Set Grid Events 7: Set Grid Package 8: Set Grid Interconnection Compliance' setData: type: object description: Same parameters as the settings of single device according to the above setting types (without “device ID”) required: - setType - setData 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/listGroupDevices: get: tags: - Groups summary: List Group Devices operationId: listGroupDevices description: List Group devices parameters: - name: groupId in: query required: false schema: type: integer description: Group Id. groupId or groupName can not both null - name: groupName in: query required: false schema: type: string description: Group name. groupId or groupName 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/fetchOperationLog: get: tags: - Modification Records summary: Query Modification Records operationId: fetchOperationLog description: Query modification records, the time span should not exceed 1 month parameters: - name: optRecordsType in: query required: true schema: type: integer description: 'Type. 0.All 1: Modify or Delete a Site 2: Edit Device Information 3: Set Energy Management Parameters 4: Set TOU Parameters 5: Set aPower Switch 6: Set Smart Circuits 7: Set Grid Events 8: Query Upgrade Record List 9: Set Grid Package 10: Set Grid Interconnection Compliance 11: Commissioning 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: queryDate in: query required: false schema: type: string description: Date - 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-sunrun/preCreatedSite: post: tags: - Sunrun summary: Site Pre-Created operationId: preCreatedSite description: Receive Sunrun Pre Created Site information requestBody: required: true content: application/json: schema: type: object properties: sites: type: array items: type: object description: This is a Json key object required: - sites 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-sunrun/backFill/data: get: tags: - Sunrun summary: BackFill API operationId: backFillData description: Get SiteId BackFill Information parameters: - name: siteId in: query required: true schema: type: string - name: startTime in: query required: true schema: type: string description: Eg:2025-01-09T00:00:00Z - name: endTime in: query required: true schema: type: string 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-sunrun/queryComponents/assets: get: tags: - Sunrun Sites summary: Query All Site Asset operationId: queryComponentsAssets description: Query all site assets of sunrun by paging parameters: - name: next in: query required: false schema: type: integer description: Search from page. Default value is 1 - name: pageSize in: query required: false schema: type: integer description: Pagination Size. Default value is 100. Max 1000 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-sunrun/setEnergyManagementParameters: post: tags: - Sunrun System Setup summary: Set Energy Management Parameters operationId: setEnergyManagementParameters description: Set energy management parameters requestBody: required: true content: application/json: schema: type: object properties: siteId: type: string description: Site ID runningMode: type: integer description: 'Running Mode. 0: Standby 1: Backup-only 2: Self-Consumption 3: TOU 5: BB&NEM 6: BB&CSS 7: BB&CGS+ The setting value should be included in the ''modeChoose'' parameter array read in ''5.2 Query Energy Management Parameters''' stopMode: type: integer description: 'Downtime maintenance mode. 0 : Default, 1 : Enabled, 2 : Disabled' stormEn: type: integer description: 'Emergency backup. 0 : Disabled, 1 : Enabled' selfBackupSoc: type: integer description: Reserved SOC in Self-consumption mode. %, 5%~80% touBackupSoc: type: integer description: Reserved SOC in TOU mode. %, 5%~80% backupMaxSoc: type: integer description: Max. SOC in Backup-only mode. %, 100% bbBackupSoc: type: integer description: Reserved SOC in BB mode. %, 5%~80% batFd: type: integer description: 'FHP feedback to the grid. 0 : Not allowed 1 : Allowed' solarFd: type: integer description: 'Solar feedback to the grid. 0 : Not allowed 1 : Allowed' gridCh: type: integer description: 'Charging from the grid. 0 : Not allowed 1 : Allowed' required: - 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-sunrun/queryEnergyManagParams: post: tags: - Sunrun System Setup summary: Query Energy Management Parameters operationId: queryEnergyManagParams description: Query energy management parameters parameters: - name: siteId in: query required: true schema: type: string description: Site 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-sunrun/setSwitchParam: post: tags: - Sunrun System Setup summary: Set aPower Switch operationId: sunrunSetSwitchParam description: Set aPower Switch requestBody: required: true content: application/json: schema: type: object properties: siteId: type: string description: Site ID cmd: type: number description: 'Type. 1 : Start up, 2 : Shut down' required: - siteId - 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-sunrun/queryApowerSwitchStatus: post: tags: - Sunrun System Setup summary: Query aPower Switch Status operationId: sunrunQueryApowerSwitchStatus description: Query aPower Switch Status parameters: - name: siteId in: query required: true schema: type: string description: Site 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' components: securitySchemes: AuthorizationToken: type: apiKey in: header name: Authorization description: Token returned by POST /api-common/tokenizer (exchange of a `cp` / `ck` credential pair). schemas: 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 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 security: - AuthorizationToken: []