{"openapi":"3.1.0","info":{"title":"Octopus Energy (BYOK) API","version":"0.1.0","description":"Octopus Energy (BYOK) lets an AI assistant read your own Octopus Energy data through the Octopus Energy API with a key you supply (Octopus Energy API key). Read-only: 8 tools (list_products, get_product, list_electricity_unit_rates, list_electricity_standing_charges, list_gas_unit_rates, list_gas_standing_charges, get_electricity_consumption, get_gas_consumption). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-octopus-energy.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-octopus-energy/docs"},"termsOfService":"https://connectorbay.com/byok-octopus-energy/terms"},"servers":[{"url":"https://byok-octopus-energy.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-octopus-energy/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_products":{"post":{"operationId":"list_products","summary":"List Octopus Energy tariff products (100 per page) with code, name, whether they are variable, green, prepay or business","description":"List Octopus Energy tariff products (100 per page) with code, name, whether they are variable, green, prepay or business, and availability dates. No account data is needed. Use for \"Which green variable Octopus tariffs are on sale right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"brand":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Brand code to filter by, for example OCTOPUS_ENERGY.","title":"Brand"},"is_variable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for variable tariffs only, false for fixed ones.","title":"Is Variable"},"is_green":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for green tariffs only.","title":"Is Green"},"is_prepay":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for prepay tariffs only.","title":"Is Prepay"},"is_business":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for business products only, false for domestic ones.","title":"Is Business"},"available_at":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Show products that were on sale at this ISO 8601 time, for example 2024-01-01T00:00Z.","title":"Available At"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_productsArguments","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_product":{"post":{"operationId":"get_product","summary":"Get one product with its electricity and gas tariff codes by region and payment method, plus current standing charge and","description":"Get one product with its electricity and gas tariff codes by region and payment method, plus current standing charge and unit rate where the product shows them. Use for \"Which tariff codes does Agile Octopus have in each region\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_code":{"description":"Octopus product code, for example 'AGILE-FLEX-22-11-25' (list_products returns the codes).","maxLength":80,"title":"Product Code","type":"string"},"tariffs_active_at":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Show prices as of this ISO 8601 time instead of now.","title":"Tariffs Active At"}},"required":["product_code"],"title":"get_productArguments","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_electricity_unit_rates":{"post":{"operationId":"list_electricity_unit_rates","summary":"List the unit rates (pence per kWh, with and without VAT) of an electricity tariff over a period; Agile gives a price fo","description":"List the unit rates (pence per kWh, with and without VAT) of an electricity tariff over a period; Agile gives a price for every half hour. Use day-unit-rates and night-unit-rates for Economy 7 tariffs. Use for \"What are the Agile Octopus half-hourly electricity prices for region C tomorrow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_code":{"description":"Octopus product code, for example 'AGILE-FLEX-22-11-25' (list_products returns the codes).","maxLength":80,"title":"Product Code","type":"string"},"tariff_code":{"description":"Electricity tariff code of that product, for example 'E-1R-AGILE-FLEX-22-11-25-C' (region letter at the end).","maxLength":100,"title":"Tariff Code","type":"string"},"rate_type":{"description":"Which rate: standard-unit-rates, day-unit-rates or night-unit-rates.","enum":["standard-unit-rates","day-unit-rates","night-unit-rates"],"title":"Rate Type","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["product_code","tariff_code","rate_type"],"title":"list_electricity_unit_ratesArguments","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_electricity_standing_charges":{"post":{"operationId":"list_electricity_standing_charges","summary":"List the daily standing charge (pence per day, with and without VAT) of an electricity tariff, with the dates each value","description":"List the daily standing charge (pence per day, with and without VAT) of an electricity tariff, with the dates each value applied. Use for \"What is the daily standing charge on Agile Octopus in region C\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_code":{"description":"Octopus product code, for example 'AGILE-FLEX-22-11-25' (list_products returns the codes).","maxLength":80,"title":"Product Code","type":"string"},"tariff_code":{"description":"Electricity tariff code of that product, for example 'E-1R-AGILE-FLEX-22-11-25-C' (region letter at the end).","maxLength":100,"title":"Tariff Code","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["product_code","tariff_code"],"title":"list_electricity_standing_chargesArguments","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_gas_unit_rates":{"post":{"operationId":"list_gas_unit_rates","summary":"List the unit rates (pence per kWh, with and without VAT) of a gas tariff over a period, with payment method where the r","description":"List the unit rates (pence per kWh, with and without VAT) of a gas tariff over a period, with payment method where the rate depends on it. Use for \"What was the gas unit rate on the standard variable tariff in region A last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_code":{"description":"Gas product code, for example 'VAR-22-11-01'.","maxLength":80,"title":"Product Code","type":"string"},"tariff_code":{"description":"Gas tariff code of that product, for example 'G-1R-VAR-22-11-01-A'.","maxLength":100,"title":"Tariff Code","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["product_code","tariff_code"],"title":"list_gas_unit_ratesArguments","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_gas_standing_charges":{"post":{"operationId":"list_gas_standing_charges","summary":"List the daily standing charge (pence per day, with and without VAT) of a gas tariff, with the dates each value applied.","description":"List the daily standing charge (pence per day, with and without VAT) of a gas tariff, with the dates each value applied. Use for \"What is the gas standing charge on the standard variable tariff in region A\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_code":{"description":"Gas product code, for example 'VAR-22-11-01'.","maxLength":80,"title":"Product Code","type":"string"},"tariff_code":{"description":"Gas tariff code of that product, for example 'G-1R-VAR-22-11-01-A'.","maxLength":100,"title":"Tariff Code","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["product_code","tariff_code"],"title":"list_gas_standing_chargesArguments","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_consumption":{"post":{"operationId":"get_electricity_consumption","summary":"Read the key owner's electricity consumption (kWh) from one smart meter, half-hourly or grouped by day, week, month or q","description":"Read the key owner's electricity consumption (kWh) from one smart meter, half-hourly or grouped by day, week, month or quarter. The MPAN and meter serial number are on the Octopus bill and in the online account. Use for \"How much electricity did my meter use each day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mpan":{"description":"MPAN of the electricity meter point (13 digits, from the bill or online account).","maxLength":20,"title":"Mpan","type":"string"},"serial_number":{"description":"Serial number of the electricity meter.","maxLength":40,"title":"Serial Number","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"order_by":{"anyOf":[{"const":"period","type":"string"},{"type":"null"}],"default":null,"description":"Use 'period' for the earliest record first; leave out for the newest first.","title":"Order By"},"group_by":{"anyOf":[{"enum":["day","week","month","quarter"],"type":"string"},{"type":"null"}],"default":null,"description":"Aggregate half-hours into day, week, month or quarter (local time); leave out for half-hourly records.","title":"Group By"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["mpan","serial_number"],"title":"get_electricity_consumptionArguments","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_gas_consumption":{"post":{"operationId":"get_gas_consumption","summary":"Read the key owner's gas consumption from one smart meter, half-hourly or grouped by day, week, month or quarter. SMETS1","description":"Read the key owner's gas consumption from one smart meter, half-hourly or grouped by day, week, month or quarter. SMETS1 meters report kWh, SMETS2 meters report cubic metres. Use for \"How much gas did my meter use per month this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mprn":{"description":"MPRN of the gas meter point (from the bill or online account).","maxLength":20,"title":"Mprn","type":"string"},"serial_number":{"description":"Serial number of the gas meter.","maxLength":40,"title":"Serial Number","type":"string"},"period_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as ISO 8601 with a Z or offset, for example 2026-10-01T00:00Z.","title":"Period From"},"period_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as ISO 8601 with a Z or offset, for example 2026-10-02T00:00Z.","title":"Period To"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Records per page (the guide says 100 is the default; this connector allows 1 to 1000).","title":"Page Size"},"order_by":{"anyOf":[{"const":"period","type":"string"},{"type":"null"}],"default":null,"description":"Use 'period' for the earliest record first; leave out for the newest first.","title":"Order By"},"group_by":{"anyOf":[{"enum":["day","week","month","quarter"],"type":"string"},{"type":"null"}],"default":null,"description":"Aggregate half-hours into day, week, month or quarter (local time); leave out for half-hourly records.","title":"Group By"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["mprn","serial_number"],"title":"get_gas_consumptionArguments","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}}}}