{"openapi":"3.1.0","info":{"title":"EnergyCAP Energy Star (BYOK) API","version":"0.1.0","description":"EnergyCAP Energy Star (BYOK) lets an AI assistant read your own EnergyCAP Energy Star data through the EnergyCAP Energy Star API with a key you supply (EnergyCAP API key). Read-only: 7 tools (list_energy_star_commodity_mappings, list_energy_star_submission_status, list_energy_star_tasks, list_portfolio_manager_properties, list_benchmark_categories, get_benchmark_settings, get_benchmark_values)....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-energycap-energystar.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-energycap-energystar/docs"},"termsOfService":"https://connectorbay.com/byok-energycap-energystar/terms"},"servers":[{"url":"https://byok-energycap-energystar.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-energycap-energystar/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_energy_star_commodity_mappings":{"post":{"operationId":"list_energy_star_commodity_mappings","summary":"List EnergyCAP commodities with their ENERGY STAR Portfolio Manager meter type, unit and delivery mapping. Use for \"How ","description":"List EnergyCAP commodities with their ENERGY STAR Portfolio Manager meter type, unit and delivery mapping. Use for \"How are my commodities mapped to ENERGY STAR meter types\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_energy_star_commodity_mappingsArguments","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_energy_star_submission_status":{"post":{"operationId":"list_energy_star_submission_status","summary":"List buildings with their ENERGY STAR submission status for each period in a range (YYYYMM), plus current size and submi","description":"List buildings with their ENERGY STAR submission status for each period in a range (YYYYMM), plus current size and submission type. Use for \"Which buildings were submitted to ENERGY STAR for September 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"submission_begin_period":{"description":"First submission period as YYYYMM, for example 202609.","maximum":299912,"minimum":190001,"title":"Submission Begin Period","type":"integer"},"submission_end_period":{"description":"Last submission period as YYYYMM (same as the first for a single period), for example 202609.","maximum":299912,"minimum":190001,"title":"Submission End Period","type":"integer"},"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the buildings returned. 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"}},"required":["submission_begin_period","submission_end_period"],"title":"list_energy_star_submission_statusArguments","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_energy_star_tasks":{"post":{"operationId":"list_energy_star_tasks","summary":"List ENERGY STAR submission and metrics-retrieval tasks with type, status, begin date, submission type and the buildings","description":"List ENERGY STAR submission and metrics-retrieval tasks with type, status, begin date, submission type and the buildings and periods involved. Paged. Use for \"What ENERGY STAR submissions ran recently and did they succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Narrow the tasks. 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: taskType equals 'Submission'.","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_energy_star_tasksArguments","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_portfolio_manager_properties":{"post":{"operationId":"list_portfolio_manager_properties","summary":"List the ENERGY STAR Portfolio Manager properties visible to EnergyCAP with use type, floor area and the EnergyCAP build","description":"List the ENERGY STAR Portfolio Manager properties visible to EnergyCAP with use type, floor area and the EnergyCAP building each is linked to. Use for \"Which Portfolio Manager properties are not yet linked to a building\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_only_unlinked":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"When true, only properties that are not yet linked to an EnergyCAP place.","title":"Include Only Unlinked"},"verbose":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"When true (default), include use type and floor area; false is faster and returns only ID and name.","title":"Verbose"}},"title":"list_portfolio_manager_propertiesArguments","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_benchmark_categories":{"post":{"operationId":"list_benchmark_categories","summary":"List the building benchmark categories (for example occupancy or production) that a benchmark slot can use. Use for \"Wha","description":"List the building benchmark categories (for example occupancy or production) that a benchmark slot can use. Use for \"What benchmark categories are available\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_benchmark_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/get_benchmark_settings":{"post":{"operationId":"get_benchmark_settings","summary":"Get the three benchmark slots (name, category and how many buildings use each) used for normalizing building energy use.","description":"Get the three benchmark slots (name, category and how many buildings use each) used for normalizing building energy use. Use for \"How are my three building benchmarks configured\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_benchmark_settingsArguments","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_benchmark_values":{"post":{"operationId":"get_benchmark_values","summary":"Get the dated values of one benchmark slot for one building or site (effective date, end date, value). Use for \"Show ben","description":"Get the dated values of one benchmark slot for one building or site (effective date, end date, value). Use for \"Show benchmark 1 values for building 56\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"benchmark_indicator":{"description":"Benchmark slot number: 1, 2 or 3.","maximum":3,"minimum":1,"title":"Benchmark Indicator","type":"integer"},"place_id":{"description":"Numeric place ID of a building or site, for example 56 (from the EnergyCAP connector's list_places).","minimum":1,"title":"Place Id","type":"integer"}},"required":["benchmark_indicator","place_id"],"title":"get_benchmark_valuesArguments","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}}}}