{"openapi":"3.1.0","info":{"title":"EnergyCAP Readings (BYOK) API","version":"0.1.0","description":"EnergyCAP Readings (BYOK) lets an AI assistant read your own EnergyCAP Readings data through the EnergyCAP Readings API with a key you supply (EnergyCAP API key). Read-only: 7 tools (list_meter_channels, get_channel, get_channel_readings, list_routes_latest_readings, list_observation_types, list_primary_uses, list_time_zones). The BYOK key travels with each request, is used for that one call only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-energycap-readings.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-energycap-readings/docs"},"termsOfService":"https://connectorbay.com/byok-energycap-readings/terms"},"servers":[{"url":"https://byok-energycap-readings.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-energycap-readings/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_meter_channels":{"post":{"operationId":"list_meter_channels","summary":"List the channels of one meter (consumption, demand and so on) with interval, first and last reading dates and the chann","description":"List the channels of one meter (consumption, demand and so on) with interval, first and last reading dates and the channel versions. Use for \"Which channels does meter 1234 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"meter_id":{"description":"Numeric meter ID, for example 1234 (from the EnergyCAP connector's list_meters).","minimum":1,"title":"Meter Id","type":"integer"}},"required":["meter_id"],"title":"list_meter_channelsArguments","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_channel":{"post":{"operationId":"get_channel","summary":"Get one meter channel by ID with code, interval, reading dates, multiplier, maximum reading, observation type and meter.","description":"Get one meter channel by ID with code, interval, reading dates, multiplier, maximum reading, observation type and meter. Use for \"Describe channel 5001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Numeric channel ID, for example 5001 (from list_meter_channels).","minimum":1,"title":"Channel Id","type":"integer"}},"required":["channel_id"],"title":"get_channelArguments","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_channel_readings":{"post":{"operationId":"get_channel_readings","summary":"Get the readings of one channel in a date range (time, value, raw value, estimated flag) with the channel unit. Defaults","description":"Get the readings of one channel in a date range (time, value, raw value, estimated flag) with the channel unit. Defaults to the last four days of data. Use for \"Show the readings of channel 5001 for September 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Numeric channel ID, for example 5001 (from list_meter_channels).","minimum":1,"title":"Channel Id","type":"integer"},"begin_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the range, inclusive (ISO 8601), for example 2026-09-01.","title":"Begin Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the range, inclusive (ISO 8601), for example 2026-09-30.","title":"End Date"}},"required":["channel_id"],"title":"get_channel_readingsArguments","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_routes_latest_readings":{"post":{"operationId":"list_routes_latest_readings","summary":"List meter-reading routes with each meter, its channels and the latest reading on each channel. Optional filter by inter","description":"List meter-reading routes with each meter, its channels and the latest reading on each channel. Optional filter by interval type. Use for \"What are the latest readings on every route\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow which channels are included, for example by interval. Filter expression: field operator 'value' pairs joined by and, every value in single quotes, operators such as equals, not equals, like, one of ('a'|'b'), between ('a'|'b'), greater than, less than.","title":"Filter"}},"title":"list_routes_latest_readingsArguments","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_observation_types":{"post":{"operationId":"list_observation_types","summary":"List the observation types (what a channel measures, for example electric use or demand) with noun and credit flag. Use ","description":"List the observation types (what a channel measures, for example electric use or demand) with noun and credit flag. Use for \"What observation types does EnergyCAP have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by nounClassCode or nounCode. Filter expression: field operator 'value' pairs joined by and, every value in single quotes, operators such as equals, not equals, like, one of ('a'|'b'), between ('a'|'b'), greater than, less than. Example: nounCode equals 'ELECTRIC'.","title":"Filter"}},"title":"list_observation_typesArguments","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_primary_uses":{"post":{"operationId":"list_primary_uses","summary":"List the primary-use categories for meters or places (for example office, school, warehouse). Use for \"Which primary use","description":"List the primary-use categories for meters or places (for example office, school, warehouse). Use for \"Which primary uses can I assign to places\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by primaryUseType (meter or place). Filter expression: field operator 'value' pairs joined by and, every value in single quotes, operators such as equals, not equals, like, one of ('a'|'b'), between ('a'|'b'), greater than, less than. Example: primaryUseType equals 'place'.","title":"Filter"}},"title":"list_primary_usesArguments","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_time_zones":{"post":{"operationId":"list_time_zones","summary":"List the supported time zones with code, name, GMT offset and daylight-saving flag. Use for \"Which time zones does Energ","description":"List the supported time zones with code, name, GMT offset and daylight-saving flag. Use for \"Which time zones does EnergyCAP support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_time_zonesArguments","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}}}}