{"openapi":"3.1.0","info":{"title":"OpenEI (BYOK) API","version":"0.1.0","description":"OpenEI (BYOK) lets an AI assistant read your own OpenEI data through the OpenEI API with a key you supply (OpenEI API key). Read-only: 6 tools (search_rates_by_coordinates, search_rates_by_address, list_rates_for_utility, list_rates_by_eia_id, list_rates_by_country, get_rate). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-openei.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-openei/docs"},"termsOfService":"https://connectorbay.com/byok-openei/terms"},"servers":[{"url":"https://byok-openei.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-openei/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/search_rates_by_coordinates":{"post":{"operationId":"search_rates_by_coordinates","summary":"Find electricity rates for utilities serving a latitude and longitude, optionally with a search radius, sector and appro","description":"Find electricity rates for utilities serving a latitude and longitude, optionally with a search radius, sector and approval filters. Use for \"What residential electricity rates apply near latitude 37.4 and longitude -122.1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"lat":{"description":"Latitude in decimal degrees.","maximum":90,"minimum":-90,"title":"Lat","type":"number"},"lon":{"description":"Longitude in decimal degrees.","maximum":180,"minimum":-180,"title":"Lon","type":"number"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"radius":{"anyOf":[{"maximum":200,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Extra search radius in miles (0 to 200, default 0).","title":"Radius"},"co_limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum number of utility companies to include in the geographic search.","title":"Co Limit"},"sector":{"anyOf":[{"enum":["Residential","Commercial","Industrial","Lighting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only rates for this sector: Residential, Commercial, Industrial or Lighting.","title":"Sector"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only rates verified by an expert, false for only unverified ones.","title":"Approved"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rates to return (1 to 500, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rates to skip, for paging.","title":"Offset"}},"required":["lat","lon"],"title":"search_rates_by_coordinatesArguments","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/search_rates_by_address":{"post":{"operationId":"search_rates_by_address","summary":"Find electricity rates for the utility serving a street address (the service geocodes it), optionally filtered by sector","description":"Find electricity rates for the utility serving a street address (the service geocodes it), optionally filtered by sector. Use for \"What commercial electricity rates apply at 1600 Amphitheatre Parkway, Mountain View, CA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"A street address or place, for example '1600 Amphitheatre Parkway, Mountain View, CA'.","maxLength":200,"title":"Address","type":"string"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"radius":{"anyOf":[{"maximum":200,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Extra search radius in miles (0 to 200, default 0).","title":"Radius"},"sector":{"anyOf":[{"enum":["Residential","Commercial","Industrial","Lighting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only rates for this sector: Residential, Commercial, Industrial or Lighting.","title":"Sector"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only rates verified by an expert, false for only unverified ones.","title":"Approved"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rates to return (1 to 500, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rates to skip, for paging.","title":"Offset"}},"required":["address"],"title":"search_rates_by_addressArguments","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_rates_for_utility":{"post":{"operationId":"list_rates_for_utility","summary":"List the rate schedules of one utility, named as in the database (the 'utility' value or page name, for example 'Detroit","description":"List the rate schedules of one utility, named as in the database (the 'utility' value or page name, for example 'Detroit Edison Co'). Use for \"List the rates of Detroit Edison Co\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"utility_name":{"description":"Utility page name, for example 'Detroit Edison Co'.","maxLength":200,"title":"Utility Name","type":"string"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"sector":{"anyOf":[{"enum":["Residential","Commercial","Industrial","Lighting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only rates for this sector: Residential, Commercial, Industrial or Lighting.","title":"Sector"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only rates verified by an expert, false for only unverified ones.","title":"Approved"},"is_default":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only the most common rate per sector and service type.","title":"Is Default"},"orderby":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by (default label).","title":"Orderby"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"asc","description":"Sort direction: asc or desc.","title":"Direction"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rates to return (1 to 500, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rates to skip, for paging.","title":"Offset"}},"required":["utility_name"],"title":"list_rates_for_utilityArguments","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_rates_by_eia_id":{"post":{"operationId":"list_rates_by_eia_id","summary":"List rate schedules of the utility with a given EIA utility id. Use for \"What rates does the utility with EIA id 5109 pu","description":"List rate schedules of the utility with a given EIA utility id. Use for \"What rates does the utility with EIA id 5109 publish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"eia":{"description":"EIA utility id, for example 5109.","maximum":999999,"minimum":1,"title":"Eia","type":"integer"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"sector":{"anyOf":[{"enum":["Residential","Commercial","Industrial","Lighting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only rates for this sector: Residential, Commercial, Industrial or Lighting.","title":"Sector"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only rates verified by an expert, false for only unverified ones.","title":"Approved"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rates to return (1 to 500, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rates to skip, for paging.","title":"Offset"}},"required":["eia"],"title":"list_rates_by_eia_idArguments","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_rates_by_country":{"post":{"operationId":"list_rates_by_country","summary":"List rate schedules for a country (ISO 3-letter code, for example USA or IND), optionally by sector; international rates","description":"List rate schedules for a country (ISO 3-letter code, for example USA or IND), optionally by sector; international rates need version 4 or higher. Use for \"Which electricity rates does the database hold for India\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"ISO 3-letter country code, for example 'IND'.","maxLength":3,"title":"Country","type":"string"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"sector":{"anyOf":[{"enum":["Residential","Commercial","Industrial","Lighting"],"type":"string"},{"type":"null"}],"default":null,"description":"Only rates for this sector: Residential, Commercial, Industrial or Lighting.","title":"Sector"},"approved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to keep only rates verified by an expert, false for only unverified ones.","title":"Approved"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many rates to return (1 to 500, default 20).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many rates to skip, for paging.","title":"Offset"}},"required":["country"],"title":"list_rates_by_countryArguments","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_rate":{"post":{"operationId":"get_rate","summary":"Get one rate schedule by its label (page name), with the minimal fields or, with detail=full, every variable including t","description":"Get one rate schedule by its label (page name), with the minimal fields or, with detail=full, every variable including tier and time-of-use structures. Use for \"Show rate 5374efea9bef51471a6965d0 in full\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"label":{"description":"The rate's label, for example '5374efea9bef51471a6965d0'.","maxLength":40,"title":"Label","type":"string"},"version":{"anyOf":[{"enum":["latest","3","4","5","6","7"],"type":"string"},{"type":"null"}],"default":"latest","description":"Database version: latest or a number from 3 to 7 (versions 4 and up include international rates).","title":"Version"},"format":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Only json is offered here.","title":"Format"},"detail":{"anyOf":[{"enum":["minimal","full"],"type":"string"},{"type":"null"}],"default":"minimal","description":"minimal (default) or full; full returns every rate variable and is large, so use a small limit with it.","title":"Detail"}},"required":["label"],"title":"get_rateArguments","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}}}}