{"openapi":"3.1.0","info":{"title":"Wattwatchers (BYOK) API","version":"0.1.0","description":"Wattwatchers (BYOK) lets an AI assistant read your own Wattwatchers data through the Wattwatchers API with a key you supply (Wattwatchers API key). Read-only: 9 tools (list_devices, get_device, list_channel_categories, list_device_models, get_short_energy, get_latest_short_energy, get_long_energy, get_latest_long_energy, get_first_long_energy). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-wattwatchers.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-wattwatchers/docs"},"termsOfService":"https://connectorbay.com/byok-wattwatchers/terms"},"servers":[{"url":"https://byok-wattwatchers.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-wattwatchers/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_devices":{"post":{"operationId":"list_devices","summary":"List the ids of all Wattwatchers devices the API key may access (no paging). Use for \"Which Wattwatchers energy monitors","description":"List the ids of all Wattwatchers devices the API key may access (no paging). Use for \"Which Wattwatchers energy monitors can my key see\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_devicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_device":{"post":{"operationId":"get_device","summary":"Get one device's last known status: label, time zone, model, firmware, last contact, signal strength, channels with CT r","description":"Get one device's last known status: label, time zone, model, firmware, last contact, signal strength, channels with CT rating and category, phase grouping and switches. Use for \"Is Wattwatchers device D123456789012 online and what are its channels\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"get_deviceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_channel_categories":{"post":{"operationId":"list_channel_categories","summary":"List the category definitions (id, label, description) that can be assigned to a device channel, such as solar or hot wa","description":"List the category definitions (id, label, description) that can be assigned to a device channel, such as solar or hot water. Use for \"What channel categories does Wattwatchers define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_channel_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_device_models":{"post":{"operationId":"list_device_models","summary":"List the valid Wattwatchers device models with display name, channel and switch counts and how they connect. Use for \"Wh","description":"List the valid Wattwatchers device models with display name, channel and switch counts and how they connect. Use for \"Which Wattwatchers device models exist and how many channels do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_device_modelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_short_energy":{"post":{"operationId":"get_short_energy","summary":"Get a device's short-interval (typically 30 second) energy readings for a time window of at most 12 hours: real and reac","description":"Get a device's short-interval (typically 30 second) energy readings for a time window of at most 12 hours: real and reactive energy, voltage, current and frequency per channel. Kept for 31 days. Use for \"Show the last hour of 30-second power readings from Wattwatchers device D123456789012\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"},"from_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Start time as Unix seconds (inclusive).","title":"From Ts"},"to_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"End time as Unix seconds (exclusive).","title":"To Ts"},"convert_energy":{"anyOf":[{"enum":["kWh","kW"],"type":"string"},{"type":"null"}],"default":null,"description":"Convert energy values to kWh or kW instead of the default watt-second based units.","title":"Convert Energy"},"group_by":{"anyOf":[{"const":"phases","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'phases' to merge channels into the device's phase groups.","title":"Group By"}},"required":["device_id"],"title":"get_short_energyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_short_energy":{"post":{"operationId":"get_latest_short_energy","summary":"Get the most recent short-interval energy reading a device sent. May be slow; prefer get_short_energy with a time window","description":"Get the most recent short-interval energy reading a device sent. May be slow; prefer get_short_energy with a time window when you know one. Use for \"What is the latest power reading from Wattwatchers device D123456789012\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"},"convert_energy":{"anyOf":[{"enum":["kWh","kW"],"type":"string"},{"type":"null"}],"default":null,"description":"Convert energy values to kWh or kW instead of the default watt-second based units.","title":"Convert Energy"},"group_by":{"anyOf":[{"const":"phases","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'phases' to merge channels into the device's phase groups.","title":"Group By"}},"required":["device_id"],"title":"get_latest_short_energyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_long_energy":{"post":{"operationId":"get_long_energy","summary":"Get a device's interval energy (5 minute up to monthly, set by granularity): real and reactive energy and voltage and cu","description":"Get a device's interval energy (5 minute up to monthly, set by granularity): real and reactive energy and voltage and current extremes per channel. Window limits: 7 days at 5m, 14 days at 15m, 31 days at 30m, 3 months hourly, 3 years daily. Use for \"How much energy did Wattwatchers device D123456789012 use each day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"},"from_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Start time as Unix seconds (inclusive).","title":"From Ts"},"to_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"End time as Unix seconds (exclusive).","title":"To Ts"},"granularity":{"anyOf":[{"enum":["5m","15m","30m","hour","day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Interval size: 5m, 15m, 30m, hour, day, week or month (default 5m).","title":"Granularity"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone such as Australia/Sydney; needed when granularity is hour or coarser.","title":"Timezone"},"convert_energy":{"anyOf":[{"enum":["kWh","kW"],"type":"string"},{"type":"null"}],"default":null,"description":"Convert energy values to kWh or kW instead of the default watt-second based units.","title":"Convert Energy"},"group_by":{"anyOf":[{"const":"phases","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'phases' to merge channels into the device's phase groups.","title":"Group By"}},"required":["device_id"],"title":"get_long_energyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_long_energy":{"post":{"operationId":"get_latest_long_energy","summary":"Get the most recent interval (5 minute) energy entry a device reported. May be slow; use get_long_energy with a window w","description":"Get the most recent interval (5 minute) energy entry a device reported. May be slow; use get_long_energy with a window when possible. Use for \"What was the latest 5-minute energy total of Wattwatchers device D123456789012\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"},"convert_energy":{"anyOf":[{"enum":["kWh","kW"],"type":"string"},{"type":"null"}],"default":null,"description":"Convert energy values to kWh or kW instead of the default watt-second based units.","title":"Convert Energy"},"group_by":{"anyOf":[{"const":"phases","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'phases' to merge channels into the device's phase groups.","title":"Group By"}},"required":["device_id"],"title":"get_latest_long_energyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_first_long_energy":{"post":{"operationId":"get_first_long_energy","summary":"Get the first interval energy entry a device ever reported, to see how far its history goes back. Use for \"When did Watt","description":"Get the first interval energy entry a device ever reported, to see how far its history goes back. Use for \"When did Wattwatchers device D123456789012 first report energy data\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Wattwatchers device id as returned by list_devices, for example 'D123456789012' (cellular) or 'ED12345678901' (WiFi).","maxLength":40,"title":"Device Id","type":"string"},"convert_energy":{"anyOf":[{"enum":["kWh","kW"],"type":"string"},{"type":"null"}],"default":null,"description":"Convert energy values to kWh or kW instead of the default watt-second based units.","title":"Convert Energy"},"group_by":{"anyOf":[{"const":"phases","type":"string"},{"type":"null"}],"default":null,"description":"Set to 'phases' to merge channels into the device's phase groups.","title":"Group By"}},"required":["device_id"],"title":"get_first_long_energyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}