{"openapi":"3.1.0","info":{"title":"OilPriceAPI (BYOK) API","version":"0.1.0","description":"OilPriceAPI (BYOK) lets an AI assistant read your own OilPriceAPI data through the OilPriceAPI API with a key you supply (OilPriceAPI key). Read-only: 11 tools (get_latest_price, get_prices_past_day, get_historical_prices, get_all_prices, list_commodities, get_commodity, get_diesel_prices, get_gasoline_prices, get_electricity_prices, get_brent_futures_curve, get_crack_spread). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-oilpriceapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-oilpriceapi/docs"},"termsOfService":"https://connectorbay.com/byok-oilpriceapi/terms"},"servers":[{"url":"https://byok-oilpriceapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-oilpriceapi/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/get_latest_price":{"post":{"operationId":"get_latest_price","summary":"Get the latest price of one commodity (the answer is the price object) or several comma-separated commodities (the price","description":"Get the latest price of one commodity (the answer is the price object) or several comma-separated commodities (the prices are in data.prices), with unit, currency, source time and freshness flags. Use for \"What is the latest Brent crude price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"by_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Commodity code or comma-separated codes, for example 'BRENT_CRUDE_USD' or 'WTI_USD,NATURAL_GAS_USD'. Use list_commodities for valid codes.","title":"By Code"},"by_type":{"anyOf":[{"enum":["spot_price","daily_average_price"],"type":"string"},{"type":"null"}],"default":null,"description":"Price type: spot_price (default) or daily_average_price.","title":"By Type"},"partial":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return the valid codes and list rejected ones instead of failing on any bad code.","title":"Partial"}},"title":"get_latest_priceArguments","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_prices_past_day":{"post":{"operationId":"get_prices_past_day","summary":"Get every price point recorded in the last 24 hours (or on one exact day) for one or more commodities, raw or aggregated","description":"Get every price point recorded in the last 24 hours (or on one exact day) for one or more commodities, raw or aggregated hourly or daily. Use for \"Show Brent crude prices over the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"by_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Commodity code or comma-separated codes, for example 'BRENT_CRUDE_USD' or 'WTI_USD,NATURAL_GAS_USD'. Use list_commodities for valid codes.","title":"By Code"},"at":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Exact observation day, YYYY-MM-DD (default: the last 24 hours).","title":"At"},"interval":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":"raw","description":"Aggregation: raw (default), hourly or daily.","title":"Interval"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Rows per page (raw up to 100, aggregated up to 500).","title":"Per Page"}},"title":"get_prices_past_dayArguments","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_historical_prices":{"post":{"operationId":"get_historical_prices","summary":"Get paginated price history for up to 5 commodity codes over a date range or a relative window (limited by the account's","description":"Get paginated price history for up to 5 commodity codes over a date range or a relative window (limited by the account's history depth), daily by default. Use for \"Show the Brent crude daily price for the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"by_code":{"description":"One commodity code or up to 5 comma-separated codes.","maxLength":200,"title":"By Code","type":"string"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Inclusive UTC start date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Inclusive UTC end date, YYYY-MM-DD.","title":"End Date"},"past":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Relative window instead of dates, such as 30d, 6m or 1y.","title":"Past"},"interval":{"anyOf":[{"enum":["raw","1h","hourly","1d","daily","1w","weekly","1m","monthly"],"type":"string"},{"type":"null"}],"default":"daily","description":"Aggregation: raw, hourly, daily (default), weekly or monthly.","title":"Interval"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Rows per page (up to 500).","title":"Per Page"}},"required":["by_code"],"title":"get_historical_pricesArguments","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_all_prices":{"post":{"operationId":"get_all_prices","summary":"Get every commodity price available to the account in one call, optionally filtered by category (oil, gas, metals, forex","description":"Get every commodity price available to the account in one call, optionally filtered by category (oil, gas, metals, forex, marine_fuels) or codes. Use for \"Give me all current energy and metals prices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"categories":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated categories: oil, gas, metals, forex, marine_fuels.","title":"Categories"},"codes":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated commodity codes.","title":"Codes"}},"title":"get_all_pricesArguments","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_commodities":{"post":{"operationId":"list_commodities","summary":"List the commodity catalog: code, name, currency, unit, category, update frequency and whether data is currently served.","description":"List the commodity catalog: code, name, currency, unit, category, update frequency and whether data is currently served. Use for \"Which commodity codes does OilPriceAPI offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_unavailable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include entries that currently have no served data.","title":"Include Unavailable"}},"title":"list_commoditiesArguments","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_commodity":{"post":{"operationId":"get_commodity","summary":"Get catalog details of one commodity code: name, unit, category, data source, update frequency and your account's histor","description":"Get catalog details of one commodity code: name, unit, category, data source, update frequency and your account's history coverage. Use for \"Tell me about the commodity code BRENT_CRUDE_USD\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"description":"Commodity code, for example 'BRENT_CRUDE_USD'.","maxLength":200,"title":"Code","type":"string"}},"required":["code"],"title":"get_commodityArguments","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_diesel_prices":{"post":{"operationId":"get_diesel_prices","summary":"Get US retail diesel prices (EIA weekly data) for the national average, a PAD district or a state. Available on the free","description":"Get US retail diesel prices (EIA weekly data) for the national average, a PAD district or a state. Available on the free tier. Use for \"What is the average diesel price in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code such as CA or TX (omit for the national average).","title":"State"}},"title":"get_diesel_pricesArguments","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_gasoline_prices":{"post":{"operationId":"get_gasoline_prices","summary":"Get US retail regular gasoline prices (EIA data) for the national average, a PAD district or selected states. Use for \"W","description":"Get US retail regular gasoline prices (EIA data) for the national average, a PAD district or selected states. Use for \"What is the national average gasoline price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code such as CA or TX (omit for the national average).","title":"State"}},"title":"get_gasoline_pricesArguments","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_prices":{"post":{"operationId":"get_electricity_prices","summary":"Get US retail electricity prices in cents per kilowatt-hour for a state (or US) and customer sector (EIA monthly data). ","description":"Get US retail electricity prices in cents per kilowatt-hour for a state (or US) and customer sector (EIA monthly data). Use for \"What is the residential electricity price in Texas\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, DC, or US for the national average.","maxLength":2,"title":"State","type":"string"},"sector":{"anyOf":[{"enum":["residential","commercial","industrial","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Customer sector: residential (default), commercial, industrial or all.","title":"Sector"}},"required":["state"],"title":"get_electricity_pricesArguments","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_brent_futures_curve":{"post":{"operationId":"get_brent_futures_curve","summary":"Get the Brent futures curve (contract months with price, volume and open interest) and its structure (contango or backwa","description":"Get the Brent futures curve (contract months with price, volume and open interest) and its structure (contango or backwardation). Needs the Scale plan. Use for \"Is the Brent futures curve in contango or backwardation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_brent_futures_curveArguments","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_crack_spread":{"post":{"operationId":"get_crack_spread","summary":"Get the current refining crack spread with its crude, gasoline and diesel legs and recent changes. Use for \"What is the ","description":"Get the current refining crack spread with its crude, gasoline and diesel legs and recent changes. Use for \"What is the current crack spread\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_crack_spreadArguments","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}}}}