{"openapi":"3.1.0","info":{"title":"WeatherAPI (BYOK) API","version":"0.1.0","description":"WeatherAPI (BYOK) lets an AI assistant read your own WeatherAPI data through the WeatherAPI API with a key you supply (API key). Read-only: 10 tools (get_current_weather, get_forecast, get_history, get_future_weather, search_locations, lookup_ip, get_astronomy, get_timezone, get_marine_weather, get_sports_events). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-weatherapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-weatherapi/docs"},"termsOfService":"https://connectorbay.com/byok-weatherapi/terms"},"servers":[{"url":"https://byok-weatherapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-weatherapi/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_current_weather":{"post":{"operationId":"get_current_weather","summary":"Get the current weather for a place: temperature, feels-like, condition, wind, humidity, precipitation, UV and cloud cov","description":"Get the current weather for a place: temperature, feels-like, condition, wind, humidity, precipitation, UV and cloud cover, optionally with air quality. Use for \"What is the weather in London right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"aqi":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":"no","description":"yes to include air quality data, no (default) to leave it out.","title":"Aqi"},"lang":{"anyOf":[{"enum":["ar","bn","bg","zh","zh_tw","cs","da","nl","fi","fr","de","el","hi","hu","it","ja","jv","ko","zh_cmn","mr","pl","pt","pa","ro","ru","sr","si","sk","es","sv","ta","te","tr","uk","ur","vi","zh_wuu","zh_hsn","zh_yue","zu"],"type":"string"},{"type":"null"}],"default":null,"description":"Language of the weather condition text.","title":"Lang"}},"required":["q"],"title":"get_current_weatherArguments","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_forecast":{"post":{"operationId":"get_forecast","summary":"Get the weather forecast for a place for 1 to 14 days (plan dependent): daily highs, lows, rain chance, astronomy and ho","description":"Get the weather forecast for a place for 1 to 14 days (plan dependent): daily highs, lows, rain chance, astronomy and hourly data, optionally with air quality and weather alerts. The answer can be large for many days; use hour to get one hour per day, or hour_fields to keep fewer fields. Use for \"What is the weather forecast for Paris for the next 3 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"days":{"anyOf":[{"maximum":14,"minimum":1,"type":"integer"},{"type":"null"}],"default":3,"description":"Number of forecast days, 1 to 14 (the plan may allow fewer).","title":"Days"},"aqi":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":"no","description":"yes to include air quality data, no (default) to leave it out.","title":"Aqi"},"alerts":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":"no","description":"yes to include government weather alerts, no (default) to leave them out.","title":"Alerts"},"hour":{"anyOf":[{"maximum":23,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this hour of the day, 0 to 23.","title":"Hour"},"hour_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated field names to keep in each hour element, for example 'time,temp_c,condition,chance_of_rain'.","title":"Hour Fields"},"lang":{"anyOf":[{"enum":["ar","bn","bg","zh","zh_tw","cs","da","nl","fi","fr","de","el","hi","hu","it","ja","jv","ko","zh_cmn","mr","pl","pt","pa","ro","ru","sr","si","sk","es","sv","ta","te","tr","uk","ur","vi","zh_wuu","zh_hsn","zh_yue","zu"],"type":"string"},{"type":"null"}],"default":null,"description":"Language of the weather condition text.","title":"Lang"}},"required":["q"],"title":"get_forecastArguments","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_history":{"post":{"operationId":"get_history","summary":"Get historical weather for a place on one date since 2010-01-01 (and up to 30 days with end_date on Pro plans): daily su","description":"Get historical weather for a place on one date since 2010-01-01 (and up to 30 days with end_date on Pro plans): daily summary, astronomy and hourly data. The answer can be large for many days; use hour to get one hour per day, or hour_fields to keep fewer fields. Use for \"What was the weather in Berlin on 1 January 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"dt":{"description":"Date, YYYY-MM-DD, on or after 2010-01-01.","maxLength":10,"title":"Dt","type":"string"},"end_dt":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Optional end date YYYY-MM-DD, after dt and at most 30 days later (Pro plan and above).","title":"End Dt"},"aqi":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":"no","description":"yes to include air quality data, no (default) to leave it out.","title":"Aqi"},"hour":{"anyOf":[{"maximum":23,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this hour of the day, 0 to 23.","title":"Hour"},"hour_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated field names to keep in each hour element, for example 'time,temp_c,condition,chance_of_rain'.","title":"Hour Fields"},"lang":{"anyOf":[{"enum":["ar","bn","bg","zh","zh_tw","cs","da","nl","fi","fr","de","el","hi","hu","it","ja","jv","ko","zh_cmn","mr","pl","pt","pa","ro","ru","sr","si","sk","es","sv","ta","te","tr","uk","ur","vi","zh_wuu","zh_hsn","zh_yue","zu"],"type":"string"},{"type":"null"}],"default":null,"description":"Language of the weather condition text.","title":"Lang"}},"required":["q","dt"],"title":"get_historyArguments","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_future_weather":{"post":{"operationId":"get_future_weather","summary":"Get the weather forecast for a single date 14 to 300 days ahead for a place. Use for \"What is the expected weather in Ro","description":"Get the weather forecast for a single date 14 to 300 days ahead for a place. Use for \"What is the expected weather in Rome on 25 December 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"dt":{"description":"Date, YYYY-MM-DD, between 14 and 300 days from today.","maxLength":10,"title":"Dt","type":"string"},"hour":{"anyOf":[{"maximum":23,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this hour of the day, 0 to 23.","title":"Hour"},"hour_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated field names to keep in each hour element, for example 'time,temp_c,condition,chance_of_rain'.","title":"Hour Fields"},"lang":{"anyOf":[{"enum":["ar","bn","bg","zh","zh_tw","cs","da","nl","fi","fr","de","el","hi","hu","it","ja","jv","ko","zh_cmn","mr","pl","pt","pa","ro","ru","sr","si","sk","es","sv","ta","te","tr","uk","ur","vi","zh_wuu","zh_hsn","zh_yue","zu"],"type":"string"},{"type":"null"}],"default":null,"description":"Language of the weather condition text.","title":"Lang"}},"required":["q","dt"],"title":"get_future_weatherArguments","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_locations":{"post":{"operationId":"search_locations","summary":"Search for places by name (autocomplete): returns matching locations with ID, name, region, country and coordinates. Use","description":"Search for places by name (autocomplete): returns matching locations with ID, name, region, country and coordinates. Use for \"Find places called Springfield\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Text to search for, for example 'Springfield' or part of a city name.","maxLength":100,"title":"Q","type":"string"}},"required":["q"],"title":"search_locationsArguments","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/lookup_ip":{"post":{"operationId":"lookup_ip","summary":"Look up the location of an IP address: city, region, country, continent, coordinates and time zone. Use for \"Where is th","description":"Look up the location of an IP address: city, region, country, continent, coordinates and time zone. Use for \"Where is the IP address 8.8.8.8 located\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"IPv4 or IPv6 address, or 'auto:ip' for the caller's own address.","maxLength":60,"title":"Q","type":"string"}},"required":["q"],"title":"lookup_ipArguments","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_astronomy":{"post":{"operationId":"get_astronomy","summary":"Get sunrise, sunset, moonrise, moonset, moon phase and moon illumination for a place on a date. Use for \"When does the s","description":"Get sunrise, sunset, moonrise, moonset, moon phase and moon illumination for a place on a date. Use for \"When does the sun set in Madrid on 21 June 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"dt":{"description":"Date, YYYY-MM-DD.","maxLength":10,"title":"Dt","type":"string"}},"required":["q","dt"],"title":"get_astronomyArguments","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_timezone":{"post":{"operationId":"get_timezone","summary":"Get the time zone ID and the current local time for a place. Use for \"What time is it in Tokyo right now\".","description":"Get the time zone ID and the current local time for a place. Use for \"What time is it in Tokyo right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"}},"required":["q"],"title":"get_timezoneArguments","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_marine_weather":{"post":{"operationId":"get_marine_weather","summary":"Get marine weather for a coastal point: wave and swell height, direction and period, tides and water temperature (Pro pl","description":"Get marine weather for a coastal point: wave and swell height, direction and period, tides and water temperature (Pro plan and above), up to 7 days. The answer can be large for many days; use hour to get one hour per day, or hour_fields to keep fewer fields. Use for \"What are the wave heights off Cornwall at 50.1,-5.5 for the next 3 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Place to look up: city name, 'lat,lon', US zip, UK postcode, Canada postal code, 'iata:LHR' airport code, 'metar:EGLL' or an IP address.","maxLength":100,"title":"Q","type":"string"},"days":{"anyOf":[{"maximum":7,"minimum":1,"type":"integer"},{"type":"null"}],"default":3,"description":"Number of days, 1 to 7 (the plan may allow fewer).","title":"Days"},"tides":{"anyOf":[{"enum":["yes","no"],"type":"string"},{"type":"null"}],"default":"no","description":"yes to include tide data, no (default) to leave it out.","title":"Tides"},"hour":{"anyOf":[{"maximum":23,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this hour of the day, 0 to 23.","title":"Hour"},"hour_fields":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated field names to keep in each hour element, for example 'time,temp_c,condition,chance_of_rain'.","title":"Hour Fields"},"lang":{"anyOf":[{"enum":["ar","bn","bg","zh","zh_tw","cs","da","nl","fi","fr","de","el","hi","hu","it","ja","jv","ko","zh_cmn","mr","pl","pt","pa","ro","ru","sr","si","sk","es","sv","ta","te","tr","uk","ur","vi","zh_wuu","zh_hsn","zh_yue","zu"],"type":"string"},{"type":"null"}],"default":null,"description":"Language of the weather condition text.","title":"Lang"}},"required":["q"],"title":"get_marine_weatherArguments","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_sports_events":{"post":{"operationId":"get_sports_events","summary":"List upcoming football, cricket and golf events matching a text search, with stadium, tournament, start time and match. ","description":"List upcoming football, cricket and golf events matching a text search, with stadium, tournament, start time and match. Use for \"What football matches are coming up for Liverpool\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Team, tournament or place to search for, for example 'Liverpool'.","maxLength":100,"title":"Q","type":"string"}},"required":["q"],"title":"get_sports_eventsArguments","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}}}}