{"openapi":"3.1.0","info":{"title":"Seniverse (BYOK) API","version":"0.1.0","description":"Seniverse (BYOK) lets an AI assistant read your own Seniverse data through the Seniverse API with a key you supply (Seniverse private API key). Read-only: 12 tools (get_weather_now, get_daily_forecast, get_hourly_forecast, get_hourly_history, get_weather_alarms, get_minutely_precipitation, get_air_now, get_air_daily_forecast, get_air_ranking, get_soil_conditions, get_tide, get_sun_times). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-seniverse.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-seniverse/docs"},"termsOfService":"https://connectorbay.com/byok-seniverse/terms"},"servers":[{"url":"https://byok-seniverse.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-seniverse/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_weather_now":{"post":{"operationId":"get_weather_now","summary":"Get current weather for a city or coordinates: condition, temperature and (paid plans) feels-like, pressure, humidity, v","description":"Get current weather for a city or coordinates: condition, temperature and (paid plans) feels-like, pressure, humidity, visibility, wind, cloud cover and dew point. Use for \"What is the weather in Beijing right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"unit":{"anyOf":[{"enum":["c","f"],"type":"string"},{"type":"null"}],"default":null,"description":"Units: c (Celsius, km/h, km, mbar; default) or f (Fahrenheit, mph, miles, inHg).","title":"Unit"}},"required":["location"],"title":"get_weather_nowArguments","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_daily_forecast":{"post":{"operationId":"get_daily_forecast","summary":"Get day and night forecasts for a city for up to 15 days (3 days on the free plan), with high and low temperature, rainf","description":"Get day and night forecasts for a city for up to 15 days (3 days on the free plan), with high and low temperature, rainfall, wind and humidity; start=-1 adds yesterday on plans that include it. Use for \"Give me the 5-day forecast for Beijing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"unit":{"anyOf":[{"enum":["c","f"],"type":"string"},{"type":"null"}],"default":null,"description":"Units: c (Celsius, km/h, km, mbar; default) or f (Fahrenheit, mph, miles, inHg).","title":"Unit"},"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day: 0 today (default), 1 tomorrow, -1 yesterday or a date like 2026/10/1.","title":"Start"},"days":{"anyOf":[{"maximum":15,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of days (limited by your plan).","title":"Days"}},"required":["location"],"title":"get_daily_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_hourly_forecast":{"post":{"operationId":"get_hourly_forecast","summary":"Get the hourly forecast for a city for up to 24 hours: condition, temperature, humidity and wind. Use for \"What is the h","description":"Get the hourly forecast for a city for up to 24 hours: condition, temperature, humidity and wind. Use for \"What is the hourly forecast for Beijing today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"unit":{"anyOf":[{"enum":["c","f"],"type":"string"},{"type":"null"}],"default":null,"description":"Units: c (Celsius, km/h, km, mbar; default) or f (Fahrenheit, mph, miles, inHg).","title":"Unit"},"start":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Hour offset to start from: 0 this hour (default), 1 next hour.","title":"Start"},"hours":{"anyOf":[{"maximum":24,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of hours (up to 24, limited by your plan).","title":"Hours"}},"required":["location"],"title":"get_hourly_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_hourly_history":{"post":{"operationId":"get_hourly_history","summary":"Get the observed weather of a city for each of the past 24 hours. Use for \"What was the weather in Seattle over the last","description":"Get the observed weather of a city for each of the past 24 hours. Use for \"What was the weather in Seattle over the last 24 hours\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"unit":{"anyOf":[{"enum":["c","f"],"type":"string"},{"type":"null"}],"default":null,"description":"Units: c (Celsius, km/h, km, mbar; default) or f (Fahrenheit, mph, miles, inHg).","title":"Unit"}},"required":["location"],"title":"get_hourly_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_weather_alarms":{"post":{"operationId":"get_weather_alarms","summary":"Get active official weather disaster warnings for a city (title, type, level, description, publication time); omit locat","description":"Get active official weather disaster warnings for a city (title, type, level, description, publication time); omit location for all of China. Use for \"Are there weather warnings in Beijing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City to query (id, name or pinyin); omit for warnings nationwide in China.","title":"Location"}},"title":"get_weather_alarmsArguments","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_minutely_precipitation":{"post":{"operationId":"get_minutely_precipitation","summary":"Get minute-by-minute rain intensity (mm/h) for the next two hours at coordinates in mainland China, with a text summary.","description":"Get minute-by-minute rain intensity (mm/h) for the next two hours at coordinates in mainland China, with a text summary. Use for \"When will the rain stop at 39.865927:116.359805\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Coordinates as 'latitude:longitude' with a colon, for example 39.865927:116.359805 (covers mainland China).","maxLength":200,"title":"Location","type":"string"}},"required":["location"],"title":"get_minutely_precipitationArguments","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_air_now":{"post":{"operationId":"get_air_now","summary":"Get current air quality of a city: AQI, PM2.5, PM10, SO2, NO2, CO, O3, main pollutant and category, optionally with ever","description":"Get current air quality of a city: AQI, PM2.5, PM10, SO2, NO2, CO, O3, main pollutant and category, optionally with every monitoring station. Use for \"What is the air quality in Beijing right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"scope":{"anyOf":[{"enum":["city","all"],"type":"string"},{"type":"null"}],"default":null,"description":"city for the city average only (default) or all to add every monitoring station.","title":"Scope"}},"required":["location"],"title":"get_air_nowArguments","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_air_daily_forecast":{"post":{"operationId":"get_air_daily_forecast","summary":"Get the daily air quality forecast for a city for up to 5 days: AQI, pollutant concentrations and category. Use for \"How","description":"Get the daily air quality forecast for a city for up to 5 days: AQI, pollutant concentrations and category. Use for \"How will the air quality in Beijing be over the next days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"days":{"anyOf":[{"maximum":5,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of days (up to 5).","title":"Days"}},"required":["location"],"title":"get_air_daily_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_air_ranking":{"post":{"operationId":"get_air_ranking","summary":"Get the nationwide ranking of Chinese cities by current AQI, best air first. Use for \"Which Chinese cities have the clea","description":"Get the nationwide ranking of Chinese cities by current AQI, best air first. Use for \"Which Chinese cities have the cleanest air right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"}},"title":"get_air_rankingArguments","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_soil_conditions":{"post":{"operationId":"get_soil_conditions","summary":"Get hourly soil temperature (5 and 10 cm) and soil relative humidity (10 and 20 cm) on a 6 km grid at coordinates in mai","description":"Get hourly soil temperature (5 and 10 cm) and soil relative humidity (10 and 20 cm) on a 6 km grid at coordinates in mainland China. Use for \"What is the soil moisture at 39.865927:116.35\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Coordinates as 'latitude:longitude' with a colon, for example 39.865927:116.359805 (covers mainland China).","maxLength":200,"title":"Location","type":"string"}},"required":["location"],"title":"get_soil_conditionsArguments","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_tide":{"post":{"operationId":"get_tide","summary":"Get hourly tide heights (cm) and daily high and low tide times for up to 18 days at a Chinese port or all ports of a cit","description":"Get hourly tide heights (cm) and daily high and low tide times for up to 18 days at a Chinese port or all ports of a city. Use for \"What are the tides near Dandong\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City to query (id, name or pinyin); returns all its ports. Use this or port.","title":"Location"},"port":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Port id, Chinese name or pinyin (for example daludao). Use this or location.","title":"Port"}},"title":"get_tideArguments","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_sun_times":{"post":{"operationId":"get_sun_times","summary":"Get sunrise and sunset times for a place worldwide for up to 15 days. Use for \"When does the sun rise and set in Beijing","description":"Get sunrise and sunset times for a place worldwide for up to 15 days. Use for \"When does the sun rise and set in Beijing this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"description":"Place to query: a Seniverse city id (for example WX4FBXXFKE4F), a city name in Chinese, English or pinyin (for example beijing), 'latitude:longitude' (for example 39.93:116.40) or an IP address.","maxLength":200,"title":"Location","type":"string"},"language":{"anyOf":[{"enum":["zh-Hans","zh-Hant","en","ja","de","fr","es","pt","hi","id","ru","th","ar"],"type":"string"},{"type":"null"}],"default":null,"description":"Response language: zh-Hans, zh-Hant, en, ja, de, fr, es, pt, hi, id, ru, th or ar (default zh-Hans).","title":"Language"},"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day: 0 today (default), -1 yesterday, 1 tomorrow or a date like 2026/10/1.","title":"Start"},"days":{"anyOf":[{"maximum":15,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of days (up to 15).","title":"Days"}},"required":["location"],"title":"get_sun_timesArguments","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}}}}