📝 Document reverse-engineered energy.comwatt.com API #1

Open

mat wants to merge 3 commits from docs/api-endpoints into main

pull from: docs/api-endpoints

merge into: mat:main

mat:main

Conversation 0 Commits 3 Files changed 11 +1420

mat commented 2026-04-24 19:27:58 +00:00

Owner

Copy link

Summary

• Adds docs/energy.comwatt.com/ (9 files + README) with field notes on the Comwatt API, reconstructed from the SPA bundle and live calls — there is no public OpenAPI/Swagger.
• Documents the new aggregations API (time-series, site-time-series, top-consumption) that replaces the old *-time-ago endpoints currently wrapped in comwatt_client/client.py (two of them now return 404 server-side).
• Captures the STOMP-over-WebSocket channel (wss://frontage.energy.comwatt.com/ws, topic /topic/sites/{siteUid}/capacityChanged) and explains why it cannot replace polling for measurement values.

Findings relevant to open work

• Issue MateoGreil/homeassistant-comwatt#40 (too many requests): GET /api/aggregations/site-time-series returns 10 site-level series in one call (productions, consumptions, injections, withdrawals, charges, discharges + the four self-* rates). ?id=A&id=B on time-series is accepted but returns the sum, not a per-device breakdown — there is no true bulk-per-device endpoint. See aggregations.md and quick-wins-for-the-python-client.md.
• The *-time-ago endpoints removed in commit e0dbcd9 are part of a wider refactor — get_site_networks_ts_time_ago and get_site_consumption_breakdown_time_ago should also migrate to the new endpoints.

Test plan

• Auth + GET /api/users/authenticated + GET /api/sites against the production frontend.
• All three /api/aggregations/* endpoints exercised live, response shapes captured in aggregations.md.
• Multi-id behaviour checked against single-id baseline (confirmed sum semantics).
• WebSocket endpoint reachability confirmed (Spring WS handler error on a malformed handshake).
• No code change yet — implementation of the quick wins is left for a follow-up PR.

## Summary - Adds `docs/energy.comwatt.com/` (9 files + README) with field notes on the Comwatt API, reconstructed from the SPA bundle and live calls — there is no public OpenAPI/Swagger. - Documents the **new aggregations API** (`time-series`, `site-time-series`, `top-consumption`) that replaces the old `*-time-ago` endpoints currently wrapped in `comwatt_client/client.py` (two of them now return 404 server-side). - Captures the **STOMP-over-WebSocket** channel (`wss://frontage.energy.comwatt.com/ws`, topic `/topic/sites/{siteUid}/capacityChanged`) and explains why it cannot replace polling for measurement values. ## Findings relevant to open work - **Issue MateoGreil/homeassistant-comwatt#40** (too many requests): `GET /api/aggregations/site-time-series` returns 10 site-level series in one call (productions, consumptions, injections, withdrawals, charges, discharges + the four self-* rates). `?id=A&id=B` on `time-series` is accepted but returns the **sum**, not a per-device breakdown — there is no true bulk-per-device endpoint. See `aggregations.md` and `quick-wins-for-the-python-client.md`. - The `*-time-ago` endpoints removed in commit e0dbcd9 are part of a wider refactor — `get_site_networks_ts_time_ago` and `get_site_consumption_breakdown_time_ago` should also migrate to the new endpoints. ## Test plan - [x] Auth + `GET /api/users/authenticated` + `GET /api/sites` against the production frontend. - [x] All three `/api/aggregations/*` endpoints exercised live, response shapes captured in `aggregations.md`. - [x] Multi-`id` behaviour checked against single-id baseline (confirmed sum semantics). - [x] WebSocket endpoint reachability confirmed (Spring WS handler error on a malformed handshake). - [ ] No code change yet — implementation of the quick wins is left for a follow-up PR.

mat added 1 commit 2026-04-24 19:27:58 +00:00

📝 Document reverse-engineered energy.comwatt.com API ... 6378e6da78

Field notes built from the SPA bundle and live calls authenticated as a
normal end-user. Covers auth, sites, devices/capacities, the new
aggregations API (per-device, site-time-series, top-consumption), the
STOMP-over-WebSocket channel and what it does/doesn't push, plus a
shopping list of quick wins for the Python client (notably the answer
to issue #40 about reducing round-trips).

mat added 1 commit 2026-04-25 15:40:40 +00:00

📝 Merge findings from second exploration of energy.comwatt.com API ... 5da48fd75e

Folds in field notes from a parallel reverse-engineering pass and the
review feedback that followed:

- WebSocket: document the SEND /app/streaming/start activation that
  unlocks live FLOW/STATE/VALUE measurements (corrects the earlier
  "no realtime channel" conclusion). Includes message body shape,
  observed cadence, capacityId conventions, and the broker tenant
  isolation issue found on wildcard subscriptions.
- New measurekeys.md: /api/measurekeys/measurekeys?siteId= — the flat
  per-site measurement inventory.
- Aggregations: add VALUE/INDEX/RATE measureKinds, AVERAGE
  aggregationType, top-consumption "others" cap, and the legacy
  site-networks-ts-time-ago variant.
- Devices: add /api/connectedobjects?siteId= and gateway 403 caveat.
- Misc: add ?deviceId= variants for plannings / alertconfigs /
  thermalcontrol, plus admin/installer-only endpoints.
- Auth: end-to-end flow walkthrough + expiry detection recipe.
- Disambiguate the capacity numeric `id` (URL paths) vs the string
  `capacityId` (WebSocket frames) — same name, different things.
- README: error/status-code conventions, refreshed TL;DR, link to all
  new files.

mat added 1 commit 2026-04-25 15:44:53 +00:00

📝 Apply doc-review feedback and add AI-disclosure banner ... 4d63759ec6

- README: AI-generated disclosure banner, one-paragraph summary,
  Gotchas section (id dualities, JSON-with-refs, WS values as strings,
  the time-series sum-vs-per-device trap, Spring's empty-list 404),
  conventions for content-type / pagination / rate limits.
- WebSocket: full copy-pasteable STOMP frame sequence (CONNECT →
  SUBSCRIBE → SEND start → MESSAGE).
- Tiles: explain what `tileChartDatas` carries.
- Capacities: mark the pilot-wire / thermal-mode `state` enums as
  unconfirmed — TODO to verify against the live capacity object.
- Move quick-wins-for-the-python-client.md out of energy.comwatt.com/
  so the API-reference directory stays purely reference; fix all
  cross-references.

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/api-endpoints:docs/api-endpoints

git switch docs/api-endpoints

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff docs/api-endpoints

git switch docs/api-endpoints

git rebase main

git switch main

git merge --ff-only docs/api-endpoints

git switch docs/api-endpoints

git rebase main

git switch main

git merge --no-ff docs/api-endpoints

git switch main

git merge --squash docs/api-endpoints

git switch main

git merge --ff-only docs/api-endpoints

git switch main

git merge docs/api-endpoints

git push origin main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

mat/python-comwatt-client!1

No description provided.