{"openapi":"3.1.0","info":{"title":"EIA (BYOK) API","version":"0.1.0","description":"EIA (BYOK) lets an AI assistant read your own EIA data through the EIA API with a key you supply (EIA open data API key). Read-only: 8 tools (describe_category, describe_route, describe_subroute, get_electricity_retail_sales, list_facet_values, get_route_data, get_subroute_data, get_series_by_legacy_id). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-eia.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-eia/docs"},"termsOfService":"https://connectorbay.com/byok-eia/terms"},"servers":[{"url":"https://byok-eia.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-eia/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/describe_category":{"post":{"operationId":"describe_category","summary":"List the child routes (datasets or sub-categories) of a top-level EIA data category, such as electricity, with id, name ","description":"List the child routes (datasets or sub-categories) of a top-level EIA data category, such as electricity, with id, name and description. Use for \"What datasets does EIA offer under electricity\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"First route segment, for example electricity.","maxLength":60,"title":"Category","type":"string"}},"required":["category"],"title":"describe_categoryArguments","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/describe_route":{"post":{"operationId":"describe_route","summary":"Describe one EIA route: its description, available frequencies, facets (filters), data columns with units, covered perio","description":"Describe one EIA route: its description, available frequencies, facets (filters), data columns with units, covered period and default frequency; or its child routes if it has any. Use for \"What frequencies, filters and data columns does electricity/retail-sales have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"First route segment, for example electricity.","maxLength":60,"title":"Category","type":"string"},"route":{"description":"Second route segment, for example retail-sales.","maxLength":80,"title":"Route","type":"string"}},"required":["category","route"],"title":"describe_routeArguments","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/describe_subroute":{"post":{"operationId":"describe_subroute","summary":"Describe one EIA route that sits three levels deep (category/route/subroute): frequencies, facets, data columns and peri","description":"Describe one EIA route that sits three levels deep (category/route/subroute): frequencies, facets, data columns and period, or its child routes. Use for \"Describe an EIA route that is three levels deep: what filters and data columns does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"First route segment, for example electricity.","maxLength":60,"title":"Category","type":"string"},"route":{"description":"Second route segment, for example retail-sales.","maxLength":80,"title":"Route","type":"string"},"subroute":{"description":"Third route segment under a route that has child routes.","maxLength":80,"title":"Subroute","type":"string"}},"required":["category","route","subroute"],"title":"describe_subrouteArguments","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_electricity_retail_sales":{"post":{"operationId":"get_electricity_retail_sales","summary":"Get U.S. electricity retail sales data (revenue, sales, average price or customer counts) by state and sector for a peri","description":"Get U.S. electricity retail sales data (revenue, sales, average price or customer counts) by state and sector for a period range; rows carry period, state, sector, the value and its units. Use for \"What was the residential electricity price in Colorado by month since 2024\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_column":{"description":"Column to return: price (cents per kWh), sales, revenue or customers.","enum":["price","sales","revenue","customers"],"title":"Data Column","type":"string"},"second_data_column":{"anyOf":[{"enum":["price","sales","revenue","customers"],"type":"string"},{"type":"null"}],"default":null,"description":"Optional second column to return.","title":"Second Data Column"},"frequency":{"anyOf":[{"enum":["monthly","quarterly","annual"],"type":"string"},{"type":"null"}],"default":null,"description":"Period type: monthly, quarterly or annual.","title":"Frequency"},"state_id":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter state code (for example CO) or a region code; omit for all states.","title":"State Id"},"sector_id":{"anyOf":[{"enum":["RES","COM","IND","TRA","OTH","ALL"],"type":"string"},{"type":"null"}],"default":null,"description":"Sector: RES residential, COM commercial, IND industrial, TRA transportation, OTH other, ALL all sectors.","title":"Sector Id"},"start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"First period to include, in the route's date format (for example 2024-01 for monthly data, 2024 for annual).","title":"Start"},"end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last period to include, in the route's date format.","title":"End"},"sort_column":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Data column or facet to sort by, for example period.","title":"Sort Column"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction for sort_column: asc or desc.","title":"Sort Direction"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of rows to skip; combine with length to page through results.","title":"Offset"},"length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows to return (1 to 1000; the service itself never returns more than 5000 rows per call).","title":"Length"}},"required":["data_column"],"title":"get_electricity_retail_salesArguments","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_facet_values":{"post":{"operationId":"list_facet_values","summary":"List the valid values of a facet (filter) of electricity retail sales, such as the sector ids with their names. Use for ","description":"List the valid values of a facet (filter) of electricity retail sales, such as the sector ids with their names. Use for \"Which sector ids can I filter electricity retail sales by\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"facet_id":{"description":"Facet to list: sectorid or stateid.","enum":["sectorid","stateid"],"title":"Facet Id","type":"string"}},"required":["facet_id"],"title":"list_facet_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}},"/v1/tools/get_route_data":{"post":{"operationId":"get_route_data","summary":"Get the data rows of any two-level EIA route (category/route), for example electricity/rto, with chosen data columns and","description":"Get the data rows of any two-level EIA route (category/route), for example electricity/rto, with chosen data columns and period range. Facet filters are not available here; use length and period limits to keep it small. Use for \"Get the 12 latest values of the price column of electricity/retail-sales\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"First route segment, for example electricity.","maxLength":60,"title":"Category","type":"string"},"route":{"description":"Second route segment, for example retail-sales.","maxLength":80,"title":"Route","type":"string"},"data_column":{"description":"Data column to return, as listed by describe_route (for example price).","maxLength":60,"title":"Data Column","type":"string"},"second_data_column":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Optional second data column to return.","title":"Second Data Column"},"frequency":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Period type the route offers, for example monthly, quarterly or annual (describe_route lists the valid ones).","title":"Frequency"},"start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"First period to include, in the route's date format (for example 2024-01 for monthly data, 2024 for annual).","title":"Start"},"end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last period to include, in the route's date format.","title":"End"},"sort_column":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Data column or facet to sort by, for example period.","title":"Sort Column"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction for sort_column: asc or desc.","title":"Sort Direction"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of rows to skip; combine with length to page through results.","title":"Offset"},"length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows to return (1 to 1000; the service itself never returns more than 5000 rows per call).","title":"Length"}},"required":["category","route","data_column"],"title":"get_route_dataArguments","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_subroute_data":{"post":{"operationId":"get_subroute_data","summary":"Get the data rows of any three-level EIA route (category/route/subroute) with chosen data columns and period range. Face","description":"Get the data rows of any three-level EIA route (category/route/subroute) with chosen data columns and period range. Facet filters are not available here. Use for \"Get the latest rows of an EIA route that is three levels deep\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"First route segment, for example electricity.","maxLength":60,"title":"Category","type":"string"},"route":{"description":"Second route segment, for example retail-sales.","maxLength":80,"title":"Route","type":"string"},"subroute":{"description":"Third route segment under a route that has child routes.","maxLength":80,"title":"Subroute","type":"string"},"data_column":{"description":"Data column to return, as listed by describe_route (for example price).","maxLength":60,"title":"Data Column","type":"string"},"second_data_column":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Optional second data column to return.","title":"Second Data Column"},"frequency":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Period type the route offers, for example monthly, quarterly or annual (describe_route lists the valid ones).","title":"Frequency"},"start":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"First period to include, in the route's date format (for example 2024-01 for monthly data, 2024 for annual).","title":"Start"},"end":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last period to include, in the route's date format.","title":"End"},"sort_column":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Data column or facet to sort by, for example period.","title":"Sort Column"},"sort_direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction for sort_column: asc or desc.","title":"Sort Direction"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of rows to skip; combine with length to page through results.","title":"Offset"},"length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Rows to return (1 to 1000; the service itself never returns more than 5000 rows per call).","title":"Length"}},"required":["category","route","subroute","data_column"],"title":"get_subroute_dataArguments","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_series_by_legacy_id":{"post":{"operationId":"get_series_by_legacy_id","summary":"Get data for an EIA version 1 series id, for example ELEC.SALES.CO-RES.A (Colorado residential electricity sales, annual","description":"Get data for an EIA version 1 series id, for example ELEC.SALES.CO-RES.A (Colorado residential electricity sales, annual), through the version 2 translation route. Use for \"Get EIA series ELEC.SALES.CO-RES.A\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"series_id":{"description":"Version 1 series id, for example ELEC.SALES.CO-RES.A.","maxLength":120,"title":"Series Id","type":"string"}},"required":["series_id"],"title":"get_series_by_legacy_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}}}}