{"openapi":"3.1.0","info":{"title":"EnergyCAP ESA (BYOK) API","version":"0.1.0","description":"EnergyCAP ESA (BYOK) lets an AI assistant read your own EnergyCAP ESA data through the EnergyCAP ESA API with a key you supply (EnergyCAP API key). Read-only: 9 tools (list_esa_channels, get_esa_channel, list_esa_channel_versions, list_data_points, get_data_point, list_esa_readings, get_esa_alert, get_sentinel_predictions, list_schedules). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-energycap-esa.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-energycap-esa/docs"},"termsOfService":"https://connectorbay.com/byok-energycap-esa/terms"},"servers":[{"url":"https://byok-energycap-esa.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-energycap-esa/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_esa_channels":{"post":{"operationId":"list_esa_channels","summary":"List interval-data channels with interval, last reading, data completeness, observation type, data point, meter and chan","description":"List interval-data channels with interval, last reading, data completeness, observation type, data point, meter and channel versions. Paged. Use for \"Which ESA interval channels exist and when did they last report\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the channels. 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: isPrimaryValue equals 'true'.","title":"Filter"},"order_by":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Ordering expression, for example channelInfo asc.","title":"Order By"},"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_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_esa_channel":{"post":{"operationId":"get_esa_channel","summary":"Get one interval-data channel by ID with interval, last reading, data completeness, observation type, data point, meter ","description":"Get one interval-data channel by ID with interval, last reading, data completeness, observation type, data point, meter and versions. Use for \"Describe ESA channel 3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"esa_channel_id":{"description":"Numeric ESA channel ID, for example 3 (from list_esa_channels).","minimum":1,"title":"Esa Channel Id","type":"integer"}},"required":["esa_channel_id"],"title":"get_esa_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/list_esa_channel_versions":{"post":{"operationId":"list_esa_channel_versions","summary":"List the versions of one ESA channel (validity dates, multiplier, offset, min and max reading, rollover, formula, unit).","description":"List the versions of one ESA channel (validity dates, multiplier, offset, min and max reading, rollover, formula, unit). Use for \"Show the version history of ESA channel 3\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"esa_channel_id":{"description":"Numeric ESA channel ID, for example 3 (from list_esa_channels).","minimum":1,"title":"Esa Channel Id","type":"integer"}},"required":["esa_channel_id"],"title":"list_esa_channel_versionsArguments","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_data_points":{"post":{"operationId":"list_data_points","summary":"List interval-data data points (sensors and meters in the ESA hierarchy) with place, commodity, model, serial number and","description":"List interval-data data points (sensors and meters in the ESA hierarchy) with place, commodity, model, serial number and channels. Paged. Use for \"Which data points are installed at Head Office\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the data points. 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: active equals 'true'.","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_data_pointsArguments","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_data_point":{"post":{"operationId":"get_data_point","summary":"Get one data point by ID with place, commodity, model, serial number, Sentinel flag and channels. Use for \"Describe data","description":"Get one data point by ID with place, commodity, model, serial number, Sentinel flag and channels. Use for \"Describe data point 789\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_point_id":{"description":"Numeric data point ID, for example 789 (from list_data_points).","minimum":1,"title":"Data Point Id","type":"integer"}},"required":["data_point_id"],"title":"get_data_pointArguments","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_readings":{"post":{"operationId":"list_esa_readings","summary":"List raw and processed interval readings with channel, timestamp, raw and processed value, unit, interval and estimated ","description":"List raw and processed interval readings with channel, timestamp, raw and processed value, unit, interval and estimated flag. Filter by channel, data point or time. Paged. Use for \"Show the raw readings of ESA channel 3 for yesterday\".","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 esaChannelId, dataPointId or timestamp. 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: esaChannelId equals '3' and timestamp greater than equal '2026-10-20'.","title":"Filter"},"order_by":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Ordering expression, for example timestamp desc.","title":"Order By"},"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_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/get_esa_alert":{"post":{"operationId":"get_esa_alert","summary":"Get one ESA threshold alert by ID: active flag, type, severity, threshold value and unit, schedule, and the channels it ","description":"Get one ESA threshold alert by ID: active flag, type, severity, threshold value and unit, schedule, and the channels it watches. Use for \"Describe ESA threshold alert 15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"esa_alert_id":{"description":"Numeric threshold alert ID, for example 15 (from the alerts field of list_esa_channels).","minimum":1,"title":"Esa Alert Id","type":"integer"}},"required":["esa_alert_id"],"title":"get_esa_alertArguments","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_sentinel_predictions":{"post":{"operationId":"get_sentinel_predictions","summary":"Get the Sentinel anomaly-detection predictions (expected value with lower and upper bound) for one ESA channel over a lo","description":"Get the Sentinel anomaly-detection predictions (expected value with lower and upper bound) for one ESA channel over a local time range. Use for \"What does Sentinel expect for ESA channel 3 today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"esa_channel_id":{"description":"Numeric ESA channel ID, for example 3 (from list_esa_channels).","minimum":1,"title":"Esa Channel Id","type":"integer"},"start_local_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the local date-time range (ISO 8601), for example 2026-10-21T00:00:00.","title":"Start Local Date"},"end_local_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the local date-time range (ISO 8601), for example 2026-10-21T23:59:59.","title":"End Local Date"}},"required":["esa_channel_id"],"title":"get_sentinel_predictionsArguments","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_schedules":{"post":{"operationId":"list_schedules","summary":"List the operating schedules (for example 24/7 or 9-5 Mon-Fri) with their per-day open hours, used by alerts and baselin","description":"List the operating schedules (for example 24/7 or 9-5 Mon-Fri) with their per-day open hours, used by alerts and baselines. Use for \"Which operating schedules are defined\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_schedulesArguments","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}}}}