# Franklin Whole Home (FranklinWH)

> FranklinWH Energy Storage Inc. builds whole-home energy management and storage hardware for
> residential solar — the aPower lithium iron phosphate AC battery, the aGate energy management
> controller, and the FranklinWH app — coordinating solar, battery, grid, generator and EV power for
> backup, self-consumption, time-of-use arbitrage and off-grid operation. Founded 2019, San
> Francisco Bay Area, sold through a certified installer and distributor channel. FranklinWH
> publishes a partner API for authorised third-party owners, financiers, installers and service
> providers to read site and device data, monitor performance, receive operational alerts and
> perform approved remote device control.

Generated by API Evangelist. FranklinWH does not publish an llms.txt of its own
(https://www.franklinwh.com/llms.txt returns 404); this file is assembled from the company's public
surface and the artifacts in this profile.

## APIs

- [FranklinWH API](https://api.franklinwh.com/): The partner API. 38 operations across a standard
  namespace (/api-common/) and a Sunrun-specific namespace (/api-sunrun/). Token auth: a cp/ck
  credential pair is exchanged at POST /api-common/tokenizer for a token sent in the Authorization
  header. Published base URL: https://test-api.franklinwh.com (free test environment). The
  production base URL is issued during partner onboarding and is not published.

## Specs

- [OpenAPI 3.1.0](openapi/franklin-whole-home-openapi.yml): API Evangelist conversion of the
  operation catalogue FranklinWH's own API portal publishes at
  https://api.franklinwh.com/js/apiList-eQeWKe2I.js. FranklinWH does not publish an OpenAPI document.
- [Overlay](overlays/franklin-whole-home-openapi-overlay.yaml): API Evangelist enhancements.

## Capabilities

- Sites — query, list (offset paginated, max 50/page), modify, delete
- Devices — inventory, device information, parameters, running status
- Device data — power, peak power, energy, power-source breakdown, telemetry grouping, inventory,
  historical load
- Warnings and events — historical device warnings, grid-outage/backup events
- System settings — time-of-use profiles, aPower battery start/stop, smart circuits (up to 3 per
  device, load shedding by state-of-charge threshold)
- Grid events — scheduled grid interactions with reserve SOC and feed-in control
- Groups — device grouping and bulk settings applied across a fleet
- Modification records — audit log of every setting change, 11 record types
- Sunrun namespace — site pre-creation, backfill, asset listing, energy-management parameters,
  aPower switch

## Semantics

- [Authentication](authentication/franklin-whole-home-authentication.yml)
- [Conventions](conventions/franklin-whole-home-conventions.yml) — pagination, error envelope, time
  formats, and the absence of idempotency
- [Errors](errors/franklin-whole-home-problem-types.yml) — application errors return HTTP 200 with a
  non-zero `code` in the body
- [Lifecycle](lifecycle/franklin-whole-home-lifecycle.yml)
- [Data model](data-model/franklin-whole-home-data-model.yml)
- [Conformance](conformance/franklin-whole-home-conformance.yml)
- [Sandbox](sandbox/franklin-whole-home-sandbox.yml)
- [Rate limits](rate-limits/franklin-whole-home-rate-limits.yml) — enforced but undocumented
- [Plans and pricing](plans/franklin-whole-home-plans-pricing.yml) — none published
- [Agentic access](agentic-access/franklin-whole-home-agentic-access.yml)
- [Agent skills](skills/_index.yml)

## Docs

- [FranklinWH](https://www.franklinwh.com/)
- [API portal](https://api.franklinwh.com/)
- [Introducing the FranklinWH API](https://www.franklinwh.com/blog/introducing-the-franklinwh-api)
- [Documentation center](https://www.franklinwh.com/support/documents/)
- [Support](https://www.franklinwh.com/support/contact/)
- [FAQ](https://www.franklinwh.com/support/articles/faq/)
- [Blog](https://www.franklinwh.com/blog/)
- [FleetView installer portal](https://energy.franklinwh.com/)
- [Become an installer](https://www.franklinwh.com/apply?role=installer)
- [Terms of use](https://www.franklinwh.com/terms-of-use/)
- [Privacy policy](https://www.franklinwh.com/policy/)

## Notes for agents

- Check the response envelope `code`, not the HTTP status. Auth failures return HTTP 200 with
  `{"code": 401, "msg": "wrong token"}` or `{"code": 403, "msg": "missing token or token param"}`.
- No idempotency key exists anywhere in this API. Several write operations start and stop a physical
  home battery or shed household circuits. Never blind-retry a write; re-read state instead.
- No rate-limit response headers and no documented 429, though FranklinWH states rate limiting is
  enforced.
- No MCP server, no A2A agent card, no /.well-known/ documents, no webhooks or AsyncAPI, and no
  first-party SDK. The packages that exist are community-maintained.