{"openapi":"3.1.0","info":{"title":"EnergyCAP EU (BYOK) API","version":"0.1.0","description":"EnergyCAP EU (BYOK) lets an AI assistant read your own EnergyCAP EU data through the EnergyCAP EU API with a key you supply (EnergyCAP API key). Read-only: 11 tools (list_meters, get_meter, list_places, get_place, list_place_types, list_commodities, list_units, list_weather_stations, list_esa_places, get_latest_esa_reading, list_esa_summarized_readings). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-energycap-eu.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-energycap-eu/docs"},"termsOfService":"https://connectorbay.com/byok-energycap-eu/terms"},"servers":[{"url":"https://byok-energycap-eu.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-energycap-eu/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_meters":{"post":{"operationId":"list_meters","summary":"List meters (utility and sub-meters) with code, name, serial number, commodity, type, building and unit. This connector ","description":"List meters (utility and sub-meters) with code, name, serial number, commodity, type, building and unit. This connector talks to the EU environment. Paged. Use for \"Which electric meters are set up in EnergyCAP\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the meters. 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: commodityCode equals 'ELECTRIC'.","title":"Filter"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows per page (1 to 1000; the service default is 250).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"}},"title":"list_metersArguments","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_meter":{"post":{"operationId":"get_meter","summary":"Get one meter by ID with its code, serial number, commodity, type, building, unit, and the channels assigned to it. Use ","description":"Get one meter by ID with its code, serial number, commodity, type, building, unit, and the channels assigned to it. Use for \"Show the details of EnergyCAP meter 1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"meter_id":{"description":"Numeric meter ID, for example 1234 (from list_meters).","minimum":1,"title":"Meter Id","type":"integer"}},"required":["meter_id"],"title":"get_meterArguments","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_places":{"post":{"operationId":"list_places","summary":"List places (portfolios, buildings, sites and spaces) with type, parent, time zone, size, build date and weather station","description":"List places (portfolios, buildings, sites and spaces) with type, parent, time zone, size, build date and weather station. Paged. Use for \"What buildings are in my EnergyCAP hierarchy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the places. 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: placeInfo like 'Office'.","title":"Filter"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows per page (1 to 1000; the service default is 250).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"}},"title":"list_placesArguments","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_place":{"post":{"operationId":"get_place","summary":"Get one place by ID with type, parent, time zone, size, ENERGY STAR flag, weather station and its child data points. Use","description":"Get one place by ID with type, parent, time zone, size, ENERGY STAR flag, weather station and its child data points. Use for \"Describe EnergyCAP place 56\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"place_id":{"description":"Numeric place ID of a building, site or space, for example 56 (from list_places).","minimum":1,"title":"Place Id","type":"integer"}},"required":["place_id"],"title":"get_placeArguments","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_place_types":{"post":{"operationId":"list_place_types","summary":"List the place types (for example building, site, space) with code, name and whether the type is a structure. Use for \"W","description":"List the place types (for example building, site, space) with code, name and whether the type is a structure. Use for \"What place types exist in EnergyCAP\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the place types. 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_place_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_commodities":{"post":{"operationId":"list_commodities","summary":"List commodities such as electric, gas and water with code, abbreviation, rollup units and whether they are in use. Use ","description":"List commodities such as electric, gas and water with code, abbreviation, rollup units and whether they are in use. Use for \"Which commodities does my EnergyCAP organization track\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow by in-use status or hierarchy. 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_commoditiesArguments","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_units":{"post":{"operationId":"list_units","summary":"List units of measure (for example kWh, therm, gallon) with code, name and type. Use for \"What units of measure does Ene","description":"List units of measure (for example kWh, therm, gallon) with code, name and type. Use for \"What units of measure does EnergyCAP know\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Optional unit-system filter. 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_unitsArguments","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_weather_stations":{"post":{"operationId":"list_weather_stations","summary":"List the weather stations available for degree-day and weather normalization, including custom stations. Use for \"Which ","description":"List the weather stations available for degree-day and weather normalization, including custom stations. Use for \"Which weather stations can EnergyCAP use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_weather_stationsArguments","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_esa_places":{"post":{"operationId":"list_esa_places","summary":"List places in the ESA (interval-data analytics) hierarchy with city, state and child data points. Paged. Use for \"Which","description":"List places in the ESA (interval-data analytics) hierarchy with city, state and child data points. Paged. Use for \"Which ESA places and data points exist for interval data\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the ESA places. 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: city equals 'Boston'.","title":"Filter"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows per page (1 to 1000; the service default is 250).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"}},"title":"list_esa_placesArguments","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_esa_reading":{"post":{"operationId":"get_latest_esa_reading","summary":"Get the most recent summarized interval reading of an ESA data point (timestamp, local timestamp, value and channel). Us","description":"Get the most recent summarized interval reading of an ESA data point (timestamp, local timestamp, value and channel). Use for \"What is the latest reading of ESA data point 789\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_point_id":{"description":"ESA data point (meter) ID, for example 789 (from list_esa_places or the readings tool).","minimum":1,"title":"Data Point Id","type":"integer"}},"required":["data_point_id"],"title":"get_latest_esa_readingArguments","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_esa_summarized_readings":{"post":{"operationId":"list_esa_summarized_readings","summary":"List summarized interval readings from ESA data points with channel, timestamp, value, unit, interval and estimated flag","description":"List summarized interval readings from ESA data points with channel, timestamp, value, unit, interval and estimated flag. Filter by data point and time. Paged. Use for \"Show the interval readings of ESA data point 789 since 1 October\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the readings, for example by esaDataPointID, timestamp, commodityInfo or estimated. 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: esaDataPointID equals '789' and timestamp greater than equal '2026-10-01'.","title":"Filter"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows per page (1 to 1000; the service default is 250).","title":"Page Size"},"page_number":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"}},"title":"list_esa_summarized_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}}}}