openapi: 3.2.0 info: title: FranklinWH Sunrun System Setup 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`). security: - AuthorizationToken: [] tags: - name: Sunrun System Setup description: Sunrun energy-management and aPower switch control. paths: /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: 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).