{ "openapi": "3.1.0", "info": { "title": "WindBorne API", "version": "0.1.0", "description": "WindBorne external API. Generated from the request and response definitions shared with the documentation. The specification lists canonical URLs; legacy route aliases remain supported." }, "servers": [ { "url": "https://api.windbornesystems.com", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "tags": [ { "name": "Atlas" }, { "name": "Models / Availability" }, { "name": "Models / Outputs" }, { "name": "Weather" }, { "name": "Webhooks" }, { "name": "Platform" } ], "paths": { "/atlas/observations/v1/super_observations": { "get": { "operationId": "get_aggregated_observations", "summary": "Super Observations", "description": "Retrieve superobbedweather observations from WindBorne's global sounding balloon constellation", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/observations/super-observations" }, "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Check `has_next_page` in the response to know when to stop.", "schema": { "type": "integer", "format": "int64", "description": "Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Check `has_next_page` in the response to know when to stop." }, "style": "form", "explode": true }, { "name": "min_time", "in": "query", "required": false, "description": "Only returns observations taken at or after this value. This filters by when the observation was taken, unlike `since`, which is used for pagination.", "schema": { "type": "integer", "format": "int64", "description": "Only returns observations taken at or after this value. This filters by when the observation was taken, unlike `since`, which is used for pagination." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Only returns observations taken at or before this value.", "schema": { "type": "integer", "format": "int64", "description": "Only returns observations taken at or before this value." }, "style": "form", "explode": true }, { "name": "include_ids", "in": "query", "required": false, "description": "If true, will include the ID of the observation and the mission that collected it.", "schema": { "type": "boolean", "default": false, "description": "If true, will include the ID of the observation and the mission that collected it." }, "style": "form", "explode": true }, { "name": "include_mission_name", "in": "query", "required": false, "description": "If true, will include the human name of the mission that collected the observation.", "schema": { "type": "boolean", "default": false, "description": "If true, will include the human name of the mission that collected the observation." }, "style": "form", "explode": true }, { "name": "include_updated_at", "in": "query", "required": false, "description": "If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data).", "schema": { "type": "boolean", "default": false, "description": "If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data)." }, "style": "form", "explode": true }, { "name": "mission_id", "in": "query", "required": false, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's observations.", "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's observations." }, "style": "form", "explode": true }, { "name": "min_latitude", "in": "query", "required": false, "description": "Southern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_latitude", "in": "query", "required": false, "description": "Northern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "min_longitude", "in": "query", "required": false, "description": "Western edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_longitude", "in": "query", "required": false, "description": "Eastern edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_next_page": { "type": "boolean", "description": "Indicates whether or not there is a subsequent page of data." }, "next_page": { "type": [ "string", "null" ], "format": "uri", "description": "The URL for the next page of data. If there is no subsequent page (i.e., `has_next_page` is false), this will be null." }, "next_since": { "type": [ "integer", "null" ], "format": "int64", "description": "Pass this value unchanged as the `since` query parameter when checking for new observations. It can be `null` when no observations are returned." }, "observations": { "type": "array", "items": { "type": "object", "properties": { "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" }, "humidity": { "type": [ "number", "null" ], "description": "Relative humidity.", "x-unit": "%" }, "specific_humidity": { "type": [ "number", "null" ], "description": "Specific humidity.", "x-unit": "mg/kg" }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude. This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude. This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row.", "x-unit": "degrees" }, "pressure": { "type": [ "number", "null" ], "description": "Pressure.", "x-unit": "hPa" }, "speed_u": { "type": [ "number", "null" ], "description": "Eastward wind component.", "x-unit": "m/s" }, "speed_v": { "type": [ "number", "null" ], "description": "Northward wind component.", "x-unit": "m/s" }, "temperature": { "type": [ "number", "null" ], "description": "Temperature.", "x-unit": "°C" }, "timestamp": { "type": "number", "description": "When the measurement was taken." }, "id": { "type": "integer", "format": "int64", "description": "The unique ID of this specific observation.", "x-present-when": "`include_ids=true`" }, "mission_id": { "type": "string", "format": "uuid", "description": "The unique ID of the mission that collected this observation.", "x-present-when": "`include_ids=true`" }, "mission_name": { "type": [ "string", "null" ], "description": "The human name of the mission that collected this observation.", "x-present-when": "`include_mission_name=true`" }, "updated_at": { "type": "number", "description": "When the observation was last updated in the database (e.g. from a re-processing of sensor data).", "x-present-when": "`include_updated_at=true`" } }, "required": [ "altitude", "humidity", "specific_humidity", "latitude", "longitude", "pressure", "speed_u", "speed_v", "temperature", "timestamp" ] }, "description": "Data points; see below for description of data point structure. In some limited cases, this may have zero elements." }, "warning": { "type": "string" } }, "required": [ "has_next_page", "next_since", "observations" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/observations/v1/soundings": { "get": { "operationId": "get_all_soundings", "summary": "Soundings", "description": "Discover which atmospheric soundings have been collected by WindBorne's global balloon constellation.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/observations/all-soundings" }, "parameters": [ { "name": "mission_id", "in": "query", "required": false, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's soundings.", "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's soundings." }, "style": "form", "explode": true }, { "name": "min_time", "in": "query", "required": false, "description": "Filter to soundings that started at or after this timestamp. Accepts Unix seconds or an ISO 8601 string.", "schema": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ], "description": "Filter to soundings that started at or after this timestamp. Accepts Unix seconds or an ISO 8601 string." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Filter to soundings that ended at or before this timestamp. Accepts Unix seconds or an ISO 8601 string.", "schema": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ], "description": "Filter to soundings that ended at or before this timestamp. Accepts Unix seconds or an ISO 8601 string." }, "style": "form", "explode": true }, { "name": "min_altitude", "in": "query", "required": false, "description": "Exclude soundings with data only below this altitude. Use to find soundings with data coverage reaching up to at least this altitude.", "schema": { "type": "number", "description": "Exclude soundings with data only below this altitude. Use to find soundings with data coverage reaching up to at least this altitude.", "x-unit": "meters" }, "style": "form", "explode": true }, { "name": "max_altitude", "in": "query", "required": false, "description": "Exclude soundings with data only above this altitude. Use to find soundings with data coverage reaching down to at least this altitude.", "schema": { "type": "number", "description": "Exclude soundings with data only above this altitude. Use to find soundings with data coverage reaching down to at least this altitude.", "x-unit": "meters" }, "style": "form", "explode": true }, { "name": "min_length", "in": "query", "required": false, "description": "Used to find soundings with a difference in altitude above this length.", "schema": { "type": "number", "description": "Used to find soundings with a difference in altitude above this length.", "x-unit": "meters" }, "style": "form", "explode": true }, { "name": "min_latitude", "in": "query", "required": false, "description": "Southern edge of the bounding box. Compares each sounding's center.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box. Compares each sounding's center." }, "style": "form", "explode": true }, { "name": "max_latitude", "in": "query", "required": false, "description": "Northern edge of the bounding box. Compares each sounding's center.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box. Compares each sounding's center." }, "style": "form", "explode": true }, { "name": "min_longitude", "in": "query", "required": false, "description": "Western edge of the bounding box. Compares each sounding's center.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box. Compares each sounding's center." }, "style": "form", "explode": true }, { "name": "max_longitude", "in": "query", "required": false, "description": "Eastern edge of the bounding box. Compares each sounding's center.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box. Compares each sounding's center." }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number.", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-indexed page number." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 64, "description": "Number of results per page." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "soundings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Uniquely identifies the sounding." }, "mission_id": { "type": "string", "format": "uuid", "description": "The mission that collected this sounding." }, "start_time": { "type": "string", "format": "date-time", "description": "When the sounding started. Omitted when unavailable." }, "end_time": { "type": "string", "format": "date-time", "description": "When the sounding ended. Omitted when unavailable." }, "min_altitude_m": { "type": [ "number", "null" ], "description": "The minimum altitude reached during the sounding.", "x-unit": "meters" }, "max_altitude_m": { "type": [ "number", "null" ], "description": "The maximum altitude reached during the sounding.", "x-unit": "meters" }, "start_lat": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "The latitude and longitude where the sounding started.", "x-unit": "degrees" }, "start_lon": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "The latitude and longitude where the sounding started.", "x-unit": "degrees" }, "end_lat": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "The latitude and longitude where the sounding ended.", "x-unit": "degrees" }, "end_lon": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "The latitude and longitude where the sounding ended.", "x-unit": "degrees" } }, "required": [ "id", "mission_id", "min_altitude_m", "max_altitude_m", "start_lat", "start_lon", "end_lat", "end_lon" ] }, "description": "Sounding metadata." }, "page": { "type": "integer", "minimum": 0, "description": "Current page number." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Number of results per page." }, "has_next_page": { "type": "boolean", "description": "Indicates whether or not there is a subsequent page of data. With area filters, keep paging until it's false; a short page doesn't mean the last page." } }, "required": [ "soundings", "page", "page_size", "has_next_page" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/constellation_status": { "get": { "operationId": "get_constellation_status", "summary": "Constellation Status", "description": "Retrieve currently flying missions with their available positions and ascent rates.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/constellation-status" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number.", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-indexed page number." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 64, "default": 64, "description": "Number of results per page." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "missions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Uniquely identifies the mission." }, "name": { "type": [ "string", "null" ], "description": "The name of the mission." }, "number": { "type": [ "integer", "null" ], "description": "The number of the mission." }, "launch_time": { "type": "string", "format": "date-time", "description": "When the balloon was launched." }, "landing_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Landing time, which may be projected while the balloon is still flying. Null if not known." }, "latitude": { "oneOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "string", "const": "restricted" } ], "description": "Latitude. Omitted together with `longitude` when the balloon has no resolvable position yet; the string `restricted` when your token may not see this balloon's location.", "x-unit": "degrees" }, "longitude": { "oneOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "string", "const": "restricted" } ], "description": "Longitude. Omitted or restricted under the same conditions as `latitude`.", "x-unit": "degrees" }, "altitude": { "oneOf": [ { "type": [ "number", "null" ] }, { "type": "string", "const": "restricted" } ], "description": "Altitude. Null when altitude is unavailable. Omitted or restricted under the same conditions as `latitude`.", "x-unit": "meters" }, "ascent_rate": { "type": [ "number", "null" ], "description": "Five-minute ascent rate from the latest transmission, positive up.", "x-unit": "m/s" }, "data_access": { "type": "boolean", "description": "Always true for missions returned by this endpoint. Does not indicate access to observation data." }, "envelope_type": { "type": [ "string", "null" ], "description": "Balloon envelope type." } }, "required": [ "id", "name", "number", "launch_time", "landing_time", "ascent_rate", "data_access" ] }, "description": "Balloon information." }, "page": { "type": "integer", "minimum": 0, "description": "Current page number." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 64, "description": "Number of results per page." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of matching results across all pages." } }, "required": [ "missions", "page", "page_size", "total" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/missions/{mission_id}/current_location": { "get": { "operationId": "get_current_location", "summary": "Current Location", "description": "Retrieve the mission's position and ascent rate.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/current-location" }, "parameters": [ { "name": "mission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." }, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" }, "ascent_rate": { "type": [ "number", "null" ], "description": "Five-minute ascent rate from the latest transmission, positive up.", "x-unit": "m/s" } }, "required": [ "latitude", "longitude", "altitude", "ascent_rate" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/missions/{mission_id}/flight_path": { "get": { "operationId": "get_flight_path", "summary": "Flight Path", "description": "Retrieve the available segments of a mission’s flight path from launch.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/flight-path" }, "parameters": [ { "name": "mission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." }, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." }, { "name": "subsample", "in": "query", "required": false, "description": "Minimum time between retained points. Each segment's first and last points are kept.", "schema": { "type": "integer", "description": "Minimum time between retained points. Each segment's first and last points are kept.", "x-unit": "seconds" }, "style": "form", "explode": true }, { "name": "ignore_landing", "in": "query", "required": false, "description": "Include points recorded after landing.", "schema": { "type": "boolean", "default": false, "description": "Include points recorded after landing." }, "style": "form", "explode": true }, { "name": "altitude_agl", "in": "query", "required": false, "description": "Return altitude above ground level when the response uses raw transmissions.", "schema": { "type": "boolean", "default": false, "description": "Return altitude above ground level when the response uses raw transmissions." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "flight_data": { "type": "array", "items": { "type": "object", "properties": { "transmit_time": { "type": "string", "format": "date-time", "description": "Time of the balloon position." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" }, "id": { "type": "string", "format": "uuid", "description": "Identifier of the source position or transmission. Omitted for estimated points." }, "synthetic": { "type": "boolean", "description": "True for an estimated position added to the flight path." }, "access_segment": { "type": "integer", "minimum": 0, "description": "Index of this point's segment in `flight_data_segments`." } }, "required": [ "transmit_time", "latitude", "longitude", "altitude", "access_segment" ] }, "description": "Balloon positions in chronological order, including latitude, longitude, and altitude." }, "flight_data_segments": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "transmit_time": { "type": "string", "format": "date-time", "description": "Time of the balloon position." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" }, "id": { "type": "string", "format": "uuid", "description": "Identifier of the source position or transmission. Omitted for estimated points." }, "synthetic": { "type": "boolean", "description": "True for an estimated position added to the flight path." }, "access_segment": { "type": "integer", "minimum": 0, "description": "Index of this point's segment in `flight_data_segments`." } }, "required": [ "transmit_time", "latitude", "longitude", "altitude", "access_segment" ] } }, "description": "The flight path split wherever data is withheld." }, "launch_site_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Mission launch site identifier." } }, "required": [ "flight_data", "flight_data_segments", "launch_site_id" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/flying_missions": { "get": { "operationId": "get_flying_missions", "summary": "Flying Missions", "description": "Retrieve information about currently flying balloon missions.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/flying-missions" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number. Increment to get the next page; if fewer than `page_size` results are returned, you've reached the last page.", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-indexed page number. Increment to get the next page; if fewer than `page_size` results are returned, you've reached the last page." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 64, "default": 64, "description": "Number of results per page." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "missions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Uniquely identifies the mission." }, "name": { "type": [ "string", "null" ], "description": "The name of the mission." }, "number": { "type": [ "integer", "null" ], "description": "The number of the mission." }, "launch_time": { "type": "string", "format": "date-time", "description": "When the balloon was launched." }, "landing_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Landing time, which may be projected while the balloon is still flying. Null if not known." }, "data_access": { "type": "boolean", "description": "Always true for missions returned by this endpoint. Does not indicate access to observation data." } }, "required": [ "id", "name", "number", "launch_time", "landing_time", "data_access" ] }, "description": "Balloon information." }, "page": { "type": "integer", "minimum": 0, "description": "Current page number." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 64, "description": "Number of results per page." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of matching results across all pages." } }, "required": [ "missions", "page", "page_size", "total" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/missions/{mission_id}/launch_site": { "get": { "operationId": "get_mission_launch_site", "summary": "Mission Launch Site", "description": "Find the launch site information for a given GSB.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/mission-launch-site" }, "parameters": [ { "name": "mission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." }, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "launch_site": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the launch site." }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "elevation": { "type": [ "number", "null" ], "description": "Launch site elevation.", "x-unit": "meters" } }, "required": [ "id", "latitude", "longitude", "elevation" ], "description": "Launch site information for the mission." } }, "required": [ "launch_site" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/positions/v1/missions/{mission_id}/predicted_path": { "get": { "operationId": "get_predicted_flight_path", "summary": "Predicted Flight Path", "description": "Get the predicted flight path for a GSB based on current conditions.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/positions/predicted-flight-path" }, "parameters": [ { "name": "mission_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." }, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prediction": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When the balloon will be at this location." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" } }, "required": [ "time", "latitude", "longitude", "altitude" ] }, "description": "Points along the predicted flight path." }, "prediction_segments": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When the balloon will be at this location." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" } }, "required": [ "time", "latitude", "longitude", "altitude" ] } }, "description": "The predicted path split wherever data is withheld.", "x-present-when": "`prediction` is not null" }, "seed_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the position used to start the prediction.", "x-present-when": "`prediction` is not null" }, "message": { "type": "string", "description": "Reason no prediction is available.", "x-present-when": "`prediction` is null" } }, "required": [ "prediction" ], "oneOf": [ { "properties": { "prediction": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When the balloon will be at this location." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude.", "x-unit": "degrees" }, "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" } }, "required": [ "time", "latitude", "longitude", "altitude" ] } } }, "required": [ "prediction_segments", "seed_time" ] }, { "properties": { "prediction": { "type": "null" } }, "required": [ "message" ] } ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/observations/v1/observations": { "get": { "operationId": "get_raw_observations", "summary": "Observations", "description": "Retrieve weather observations from WindBorne's global sounding balloon constellation", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/observations/observations" }, "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Check `has_next_page` in the response to know when to stop.", "schema": { "type": "integer", "format": "int64", "description": "Pagination cursor. Use a Unix timestamp in seconds to start from a known point. Pass returned cursor values unchanged. Check `has_next_page` in the response to know when to stop." }, "style": "form", "explode": true }, { "name": "min_time", "in": "query", "required": false, "description": "Only returns observations taken at or after this value. This filters by when the observation was taken, unlike `since`, which is used for pagination.", "schema": { "type": "integer", "format": "int64", "description": "Only returns observations taken at or after this value. This filters by when the observation was taken, unlike `since`, which is used for pagination." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Only returns observations taken at or before this value.", "schema": { "type": "integer", "format": "int64", "description": "Only returns observations taken at or before this value." }, "style": "form", "explode": true }, { "name": "include_ids", "in": "query", "required": false, "description": "If true, will include the ID of the observation and the mission that collected it.", "schema": { "type": "boolean", "default": false, "description": "If true, will include the ID of the observation and the mission that collected it." }, "style": "form", "explode": true }, { "name": "include_mission_name", "in": "query", "required": false, "description": "If true, will include the human name of the mission that collected the observation.", "schema": { "type": "boolean", "default": false, "description": "If true, will include the human name of the mission that collected the observation." }, "style": "form", "explode": true }, { "name": "include_updated_at", "in": "query", "required": false, "description": "If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data).", "schema": { "type": "boolean", "default": false, "description": "If true, will include when the observation was last updated in the database (e.g. from a re-processing of sensor data)." }, "style": "form", "explode": true }, { "name": "mission_id", "in": "query", "required": false, "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's observations.", "schema": { "type": "string", "format": "uuid", "description": "ID of a WindBorne balloon mission, as listed by [Flying Missions](/atlas/version_1/positions/flying-missions/). Returns only that mission's observations." }, "style": "form", "explode": true }, { "name": "min_latitude", "in": "query", "required": false, "description": "Southern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_latitude", "in": "query", "required": false, "description": "Northern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "min_longitude", "in": "query", "required": false, "description": "Western edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_longitude", "in": "query", "required": false, "description": "Eastern edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_next_page": { "type": "boolean", "description": "Indicates whether or not there is a subsequent page of data." }, "next_page": { "type": [ "string", "null" ], "format": "uri", "description": "The URL for the next page of data. If there is no subsequent page (i.e., `has_next_page` is false), this will be null." }, "next_since": { "type": [ "integer", "null" ], "format": "int64", "description": "Pass this value unchanged as the `since` query parameter when checking for new observations. It can be `null` when no observations are returned." }, "observations": { "type": "array", "items": { "type": "object", "properties": { "altitude": { "type": [ "number", "null" ], "description": "Altitude.", "x-unit": "meters" }, "humidity": { "type": [ "number", "null" ], "description": "Relative humidity.", "x-unit": "%" }, "specific_humidity": { "type": [ "number", "null" ], "description": "Specific humidity.", "x-unit": "mg/kg" }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude. This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude. This is reported at lower frequency (once per downlink packet), then broadcast to the other measurements, and thus will be the same for multiple observations in a row.", "x-unit": "degrees" }, "pressure": { "type": [ "number", "null" ], "description": "Pressure.", "x-unit": "hPa" }, "speed_u": { "type": [ "number", "null" ], "description": "Eastward wind component.", "x-unit": "m/s" }, "speed_v": { "type": [ "number", "null" ], "description": "Northward wind component.", "x-unit": "m/s" }, "temperature": { "type": [ "number", "null" ], "description": "Temperature.", "x-unit": "°C" }, "timestamp": { "type": "number", "description": "When the measurement was taken." }, "id": { "type": "integer", "format": "int64", "description": "The unique ID of this specific observation.", "x-present-when": "`include_ids=true`" }, "mission_id": { "type": "string", "format": "uuid", "description": "The unique ID of the mission that collected this observation.", "x-present-when": "`include_ids=true`" }, "mission_name": { "type": [ "string", "null" ], "description": "The human name of the mission that collected this observation.", "x-present-when": "`include_mission_name=true`" }, "updated_at": { "type": "number", "description": "When the observation was last updated in the database (e.g. from a re-processing of sensor data).", "x-present-when": "`include_updated_at=true`" } }, "required": [ "altitude", "humidity", "specific_humidity", "latitude", "longitude", "pressure", "speed_u", "speed_v", "temperature", "timestamp" ] }, "description": "Data points; see below for description of data point structure. In some limited cases, this may have zero elements." }, "warning": { "type": "string" } }, "required": [ "has_next_page", "next_since", "observations" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/atlas/observations/v1/soundings/{sounding_id}": { "get": { "operationId": "get_sounding", "summary": "Sounding by ID", "description": "Retrieve full atmospheric sounding data for a specific sounding ID.", "tags": [ "Atlas" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/atlas/version_1/observations/sounding" }, "parameters": [ { "name": "sounding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the sounding to retrieve. Sounding IDs can be obtained from the [Soundings](/atlas/version_1/observations/all-soundings/) endpoint." }, "description": "The unique identifier of the sounding to retrieve. Sounding IDs can be obtained from the [Soundings](/atlas/version_1/observations/all-soundings/) endpoint." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sounding_id": { "type": "string", "format": "uuid", "description": "Unique sounding identifier." }, "mission_id": { "type": "string", "format": "uuid", "description": "Mission that collected this sounding." }, "data": { "type": "array", "items": { "type": "object", "properties": { "pressure_hpa": { "type": [ "number", "null" ], "description": "Atmospheric pressure.", "x-unit": "hPa" }, "altitude_m": { "type": [ "number", "null" ], "description": "Altitude above mean sea level.", "x-unit": "meters" }, "temperature_c": { "type": [ "number", "null" ], "description": "Air temperature.", "x-unit": "°C" }, "dewpoint_c": { "type": [ "number", "null" ], "description": "Dewpoint. Calculated from temperature and relative humidity.", "x-unit": "°C" }, "specific_humidity_mg_kg": { "type": [ "number", "null" ], "description": "Specific humidity.", "x-unit": "mg/kg" }, "relative_humidity_pct": { "type": [ "number", "null" ], "description": "Relative humidity.", "x-unit": "%" }, "wind_u_ms": { "type": [ "number", "null" ], "description": "Eastward wind component. Direction of increasing longitude.", "x-unit": "m/s" }, "wind_v_ms": { "type": [ "number", "null" ], "description": "Northward wind component. Direction of increasing latitude.", "x-unit": "m/s" }, "time": { "type": "string", "format": "date-time", "description": "Measurement timestamp." }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude. May vary as balloon travels horizontally.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude. May vary as balloon travels horizontally.", "x-unit": "degrees" } }, "required": [ "pressure_hpa", "altitude_m", "temperature_c", "dewpoint_c", "specific_humidity_mg_kg", "relative_humidity_pct", "wind_u_ms", "wind_v_ms", "time", "latitude", "longitude" ] }, "description": "Atmospheric data at different altitudes, ordered by altitude." } }, "required": [ "sounding_id", "mission_id", "data" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." } } } }, "/models/v1/{model}/initialization_times": { "get": { "operationId": "get_initialization_times", "summary": "Initialization Times", "description": "List available model initialization times for forecasts.", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/initialization-times" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "domain", "in": "query", "required": false, "description": "Regional domain to retrieve.", "schema": { "type": "string", "enum": [ "conus" ], "default": "conus", "description": "Regional domain to retrieve.", "x-available-on": [ "wm-6-3km" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6-3km" ] } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Available initialization times. Ordered from oldest to newest." }, "in_progress": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization time currently being generated (if any)." }, "incomplete": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times whose generation is incomplete. Used to debug generation issues and forecast delivery issues." }, "latest": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest available initialization time." } }, "required": [ "available", "in_progress", "incomplete", "latest" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/initialization_times/archive": { "get": { "operationId": "get_archived_initialization_times", "summary": "Archived Initialization Times", "description": "List archived initialization times for forecast models.", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/archived-initialization-times" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number. Negative values are treated as 0.", "schema": { "type": "integer", "default": 0, "description": "Zero-indexed page number. Negative values are treated as 0." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page. Values below 1 or above 500 are clamped to that range.", "schema": { "type": "integer", "default": 64, "description": "Number of results per page. Values below 1 or above 500 are clamped to that range." }, "style": "form", "explode": true }, { "name": "order", "in": "query", "required": false, "description": "Sort order: `newest` returns most recent first, `oldest` returns earliest first.", "schema": { "type": "string", "enum": [ "newest", "oldest" ], "default": "newest", "description": "Sort order: `newest` returns most recent first, `oldest` returns earliest first." }, "style": "form", "explode": true }, { "name": "domain", "in": "query", "required": false, "description": "Regional domain to retrieve.", "schema": { "type": "string", "enum": [ "conus" ], "default": "conus", "description": "Regional domain to retrieve.", "x-available-on": [ "wm-6-3km" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6-3km" ] } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "archived_initialization_times": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Available historical initialization times for point forecasts." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of archived initialization times available across all pages." }, "page": { "type": "integer", "minimum": 0, "description": "Current page number." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Number of results per page." } }, "required": [ "archived_initialization_times", "total", "page", "page_size" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/variables": { "get": { "operationId": "get_variables", "summary": "Variables", "description": "List available variables and vertical levels for a given model.", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/variables" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "mm", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "sfc_variables": { "type": "array", "items": { "type": "string" }, "description": "Surface-level variable identifiers." }, "upper_variables": { "type": "array", "items": { "type": "string" }, "description": "Upper-air variable identifiers." }, "derived_sfc_variables": { "type": "array", "items": { "type": "string" }, "description": "Derived surface-level variable identifiers. Not included when requesting all variables; request individually.", "x-available-on": [ "wm-6" ] }, "derived_upper_variables": { "type": "array", "items": { "type": "string" }, "description": "Derived upper-air variable identifiers. Not included when requesting all variables; request individually.", "x-available-on": [ "wm-6" ] }, "levels": { "type": [ "array", "null" ], "items": { "type": [ "integer", "string" ] }, "description": "Available vertical levels. Pressure levels are given in hPa." }, "distribution_details": { "type": "object", "properties": { "sfc_variables": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "description": "Available distribution outputs for this surface variable. Values: `mean`, `std`, `det`, `members`, percentiles, thresholds, or precipitation-type probabilities.", "x-available-on": [ "wm-6" ] }, "description": "Surface variables, each mapping to its available distribution outputs.", "x-available-on": [ "wm-6" ] }, "upper_variables": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "description": "Distribution outputs available at this pressure level. Typically `mean`, `std`, and `det`. Some levels include additional percentiles (`p01`–`p99`) or `members`.", "x-available-on": [ "wm-6" ] }, "description": "Available distribution outputs for this upper-air variable, keyed by level.", "x-available-on": [ "wm-6" ] }, "description": "Upper-air variables, each mapping to an object keyed by pressure level.", "x-available-on": [ "wm-6" ] }, "derived_sfc_variables": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "description": "Available distribution outputs for this derived surface variable.", "x-available-on": [ "wm-6" ] }, "description": "Derived surface variables, each mapping to its available distribution outputs.", "x-available-on": [ "wm-6" ] }, "derived_upper_variables": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "description": "Optional distribution outputs specific to this pressure level.", "x-available-on": [ "wm-6" ] }, "properties": { "default": { "type": "array", "items": { "type": "string" }, "description": "Distribution outputs available at all pressure levels.", "x-available-on": [ "wm-6" ] } }, "description": "Available distribution outputs for this derived upper-air variable.", "x-available-on": [ "wm-6" ] }, "description": "Derived upper-air variables, each mapping to an object keyed by pressure level.", "x-available-on": [ "wm-6" ] } }, "description": "Available distribution outputs grouped by native and derived surface and upper-air variables.", "x-available-on": [ "wm-6" ] } }, "required": [ "sfc_variables", "upper_variables", "derived_sfc_variables", "derived_upper_variables", "levels", "distribution_details" ] }, { "type": "object", "properties": { "model": { "type": "string" }, "subset": { "type": [ "string", "null" ] } }, "required": [ "model", "subset" ] } ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/calculation_times/{calculation_type}": { "get": { "operationId": "get_calculation_times", "summary": "Calculation Times", "description": "List available calculation times for degree day and tropical cyclone forecasts.", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/calculation_times" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "wm-4.5-ens-mean", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "gefs" ], "description": "Forecast model whose calculation availability to return. Degree days support all listed models; tropical_cyclones supports only wm-6." }, "description": "Forecast model whose calculation availability to return. Degree days support all listed models; tropical_cyclones supports only wm-6." }, { "name": "calculation_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "degree_days", "tropical_cyclones" ], "description": "Calculation product whose availability to return. Use `degree_days` for HDD/CDD forecasts. Use `tropical_cyclones` for tropical cyclone forecasts (`wm-6` only)." }, "description": "Calculation product whose availability to return. Use `degree_days` for HDD/CDD forecasts. Use `tropical_cyclones` for tropical cyclone forecasts (`wm-6` only)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times with completed calculations for the requested calculation type. Ordered from newest to oldest." }, "in_progress": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times with calculations currently in progress for the requested calculation type." }, "incomplete": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times with incomplete calculations for the requested calculation type. Used to debug calculation issues." }, "latest": { "type": "string", "format": "date-time", "description": "Latest available initialization time with completed calculations." } }, "required": [ "available", "in_progress", "incomplete", "latest" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/mm/point_forecast/stations": { "get": { "operationId": "get_available_stations", "summary": "Available Stations", "description": "List all weather stations with point forecasts", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/available-stations" }, "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "station_id": { "type": "string", "description": "The ICAO station identifier." }, "station_name": { "type": [ "string", "null" ], "description": "Name of the weather station, or null when unavailable." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" } }, "required": [ "station_id", "station_name", "latitude", "longitude" ] } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/run_information": { "get": { "operationId": "get_run_information", "summary": "Run Information", "description": "Get information for a specific model run", "tags": [ "Models / Availability" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/availability/run-information" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "type": "string", "minLength": 1, "description": "The initialization time for the forecast." }, "style": "form", "explode": true }, { "name": "ens_member", "in": "query", "required": false, "description": "The ensemble member to query run information for.", "schema": { "anyOf": [ { "type": "string", "enum": [ "mean" ] }, { "type": "integer" } ], "description": "The ensemble member to query run information for.", "x-available-on": [ "ecmwf-ens" ] }, "style": "form", "explode": true, "x-available-on": [ "ecmwf-ens" ] }, { "name": "domain", "in": "query", "required": false, "description": "Regional domain to retrieve.", "schema": { "type": "string", "enum": [ "conus" ], "default": "conus", "description": "Regional domain to retrieve.", "x-available-on": [ "wm-6-3km" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6-3km" ] } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "in_progress": { "type": "boolean", "description": "Whether generation is still in progress." }, "available": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "description": "Available forecast hour. The valid time is `forecast_zero` + `forecast_hour`.", "x-unit": "hours" }, "archived": { "type": "boolean", "description": "Whether the hour has been archived." }, "created_at": { "type": "string", "format": "date-time", "description": "Time the output for this forecast hour was generated." } }, "required": [ "forecast_hour", "archived", "created_at" ] }, "description": "Available forecast hours and metadata." } }, "required": [ "initialization_time", "forecast_zero", "in_progress", "available" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/gridded": { "get": { "operationId": "get_gridded_forecast", "summary": "Gridded Forecast", "description": "Download gridded forecast output as NetCDF.", "tags": [ "Models / Outputs" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/outputs/gridded-forecast" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "variable", "in": "query", "required": true, "description": "Variable to download. Use the [Variables](/models/version_1/availability/variables/) endpoint to list what's available for your model. Set `all` to retrieve all native variables at all heights. Specify a surface variable (e.g., `temperature_2m`) or combine with `level` for upper-level variables (e.g., `temperature` at 500 hPa). On `wm-6`, derived variables (e.g., `thermal_strength`, or `edr` at 500 hPa) must be requested by name and are available only for non-archived forecasts.", "schema": { "type": "string", "minLength": 1, "description": "Variable to download. Use the [Variables](/models/version_1/availability/variables/) endpoint to list what's available for your model. Set `all` to retrieve all native variables at all heights. Specify a surface variable (e.g., `temperature_2m`) or combine with `level` for upper-level variables (e.g., `temperature` at 500 hPa). On `wm-6`, derived variables (e.g., `thermal_strength`, or `edr` at 500 hPa) must be requested by name and are available only for non-archived forecasts." }, "style": "form", "explode": true }, { "name": "level", "in": "query", "required": false, "description": "Pressure level for upper-level variables.", "schema": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "Pressure level for upper-level variables.", "x-unit": "hPa", "x-available-on": [ "wm-6", "wm-6-3km" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6", "wm-6-3km" ] }, { "name": "include_distribution", "in": "query", "required": false, "description": "If true, adds distribution outputs such as percentiles, standard deviation, thresholds, and precipitation-type probabilities. Only available for selected variables. Available only with `format=zarr`.", "schema": { "type": "boolean", "default": false, "description": "If true, adds distribution outputs such as percentiles, standard deviation, thresholds, and precipitation-type probabilities. Only available for selected variables. Available only with `format=zarr`.", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "include_deterministic", "in": "query", "required": false, "description": "If true, adds the deterministic forecast to the output. Only available for WM-6 variables reported with `det` by the [Variables](/models/version_1/availability/variables/) endpoint. Available only with `format=zarr`.", "schema": { "type": "boolean", "default": false, "description": "If true, adds the deterministic forecast to the output. Only available for WM-6 variables reported with `det` by the [Variables](/models/version_1/availability/variables/) endpoint. Available only with `format=zarr`.", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "include_members", "in": "query", "required": false, "description": "If true, adds all 128 ensemble members to the output. Only available for selected variables. Available only with `format=zarr`.", "schema": { "type": "boolean", "default": false, "description": "If true, adds all 128 ensemble members to the output. Only available for selected variables. Available only with `format=zarr`.", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "skip_mean", "in": "query", "required": false, "description": "If true, omits the ensemble mean from the output. Requires `include_deterministic` or `include_members`. Cannot be combined with `include_distribution`. Only available for WM-6 with `format=zarr`.", "schema": { "type": "boolean", "default": false, "description": "If true, omits the ensemble mean from the output. Requires `include_deterministic` or `include_members`. Cannot be combined with `include_distribution`. Only available for WM-6 with `format=zarr`.", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "time", "in": "query", "required": false, "description": "The time at which the forecast is valid. Alternatively, you can specify `initialization_time` and `forecast_hour`.", "schema": { "type": "string", "minLength": 1, "description": "The time at which the forecast is valid. Alternatively, you can specify `initialization_time` and `forecast_hour`." }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast. Use with `forecast_hour`, or with `time` to select a forecast from this model run.", "schema": { "type": "string", "minLength": 1, "description": "The initialization time for the forecast. Use with `forecast_hour`, or with `time` to select a forecast from this model run." }, "style": "form", "explode": true }, { "name": "forecast_hour", "in": "query", "required": false, "description": "Hours from `forecast_zero` for which to get the forecast. Use with `initialization_time`, or with `time` to restrict the forecast hour.", "schema": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "Hours from `forecast_zero` for which to get the forecast. Use with `initialization_time`, or with `time` to restrict the forecast hour.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "format", "in": "query", "required": false, "description": "Output file format.", "schema": { "type": "string", "enum": [ "zarr", "netcdf" ], "description": "Output file format." }, "style": "form", "explode": true }, { "name": "domain", "in": "query", "required": false, "description": "Regional domain to retrieve.", "schema": { "type": "string", "enum": [ "conus" ], "default": "conus", "description": "Regional domain to retrieve.", "x-available-on": [ "wm-6-3km" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6-3km" ] }, { "name": "as_url", "in": "query", "required": false, "description": "If true, returns a JSON response with a temporary download URL instead of the file directly. On `wm-6` and `wm-6-3km`, for a single variable or level, the response also lists the byte ranges in that file (`parts`) that hold your selection. On other models, only available with `variable=all`; the URL is the whole file. Useful for MCP clients and programmatic access.", "schema": { "type": "boolean", "default": false, "description": "If true, returns a JSON response with a temporary download URL instead of the file directly. On `wm-6` and `wm-6-3km`, for a single variable or level, the response also lists the byte ranges in that file (`parts`) that hold your selection. On other models, only available with `variable=all`; the URL is the whole file. Useful for MCP clients and programmatic access." }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "time" ] }, { "required": [ "initialization_time", "forecast_hour" ] } ], "allOf": [ { "if": { "anyOf": [ { "required": [ "include_distribution" ], "properties": { "include_distribution": { "const": true } } }, { "required": [ "include_members" ], "properties": { "include_members": { "const": true } } }, { "required": [ "include_deterministic" ], "properties": { "include_deterministic": { "const": true } } }, { "required": [ "skip_mean" ], "properties": { "skip_mean": { "const": true } } } ] }, "then": { "properties": { "format": { "const": "zarr" } } } }, { "if": { "required": [ "skip_mean" ], "properties": { "skip_mean": { "const": true } } }, "then": { "anyOf": [ { "required": [ "include_deterministic" ], "properties": { "include_deterministic": { "const": true } } }, { "required": [ "include_members" ], "properties": { "include_members": { "const": true } } } ], "properties": { "include_distribution": { "const": false } } } } ] }, "responses": { "200": { "description": "NetCDF or Zarr ZIP data, or JSON download metadata when as_url=true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Presigned download URL. When `parts` is present, this points to the full archive." }, "warning": { "type": "string", "description": "Warning about the download, when provided." }, "variable": { "type": "string", "description": "Selected variable.", "x-present-when": "`parts` is present" }, "url_expires_at": { "type": "string", "format": "date-time", "description": "When `url` expires.", "x-present-when": "`parts` is present" }, "subset_bytes": { "type": "integer", "minimum": 0, "description": "Total size of the selected byte ranges and decoded inline content.", "x-unit": "bytes", "x-present-when": "`parts` is present" }, "parts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Path of this entry within the Zarr store." }, "range": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer", "minimum": 0 }, "description": "Inclusive `[start, end]` byte offsets in `url`. Fetch with `Range: bytes=start-end`." }, "inline": { "type": "string", "format": "byte", "description": "Base64-encoded entry content, supplied instead of a byte range." } }, "required": [ "path" ], "oneOf": [ { "required": [ "range" ], "not": { "required": [ "inline" ] } }, { "required": [ "inline" ], "not": { "required": [ "range" ] } } ] }, "description": "Entries needed to assemble the selected Zarr data. Each supplies either `range` or `inline`." } }, "required": [ "url" ], "anyOf": [ { "not": { "required": [ "parts" ] } }, { "required": [ "variable", "url_expires_at", "subset_bytes" ] } ] } }, "application/x-netcdf": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "303": { "description": "Download the forecast from the signed URL in Location.", "headers": { "Location": { "description": "Signed download URL.", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/point_forecast/interpolated": { "get": { "operationId": "get_interpolated_point_forecast", "summary": "Interpolated Point Forecast", "description": "Interpolate gridded output to get forecasts at arbitrary coordinates.", "tags": [ "Models / Outputs" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/outputs/interpolated-point-forecast" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "hrrr" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "coordinates", "in": "query", "required": true, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order. On `wm-6-3km`, coordinates must fall within the model's bounding box.", "schema": { "type": "string", "minLength": 1, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order. On `wm-6-3km`, coordinates must fall within the model's bounding box." }, "style": "form", "explode": true }, { "name": "variable", "in": "query", "required": false, "description": "Comma-separated model variable(s) to interpolate instead of the default variable set. On WM-6, request a native variable (e.g., `temperature_2m`) or a derived variable (e.g., `thermal_strength`) by name; for upper-level variables, also specify `level`. Derived variables are not included in the default set and are available only for non-archived forecasts. Use the [Variables](/models/version_1/availability/variables/) endpoint to list what's available.", "schema": { "type": "string", "minLength": 1, "description": "Comma-separated model variable(s) to interpolate instead of the default variable set. On WM-6, request a native variable (e.g., `temperature_2m`) or a derived variable (e.g., `thermal_strength`) by name; for upper-level variables, also specify `level`. Derived variables are not included in the default set and are available only for non-archived forecasts. Use the [Variables](/models/version_1/availability/variables/) endpoint to list what's available." }, "style": "form", "explode": true }, { "name": "level", "in": "query", "required": false, "description": "Pressure level for an upper-level variable, in hPa. See [Variables](/models/version_1/availability/variables/) for the levels available for the selected model.", "schema": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "Pressure level for an upper-level variable, in hPa. See [Variables](/models/version_1/availability/variables/) for the levels available for the selected model.", "x-unit": "hPa", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "include_distribution", "in": "query", "required": false, "description": "If true, adds distribution outputs such as percentiles, standard deviation, thresholds, and precipitation-type probabilities. Requires `variable` to be set to a single variable.", "schema": { "type": "boolean", "default": false, "description": "If true, adds distribution outputs such as percentiles, standard deviation, thresholds, and precipitation-type probabilities. Requires `variable` to be set to a single variable.", "x-available-on": [ "wm-6" ] }, "style": "form", "explode": true, "x-available-on": [ "wm-6" ] }, { "name": "min_forecast_time", "in": "query", "required": false, "description": "Earliest valid time to include in the response.", "schema": { "type": "string", "minLength": 1, "description": "Earliest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "max_forecast_time", "in": "query", "required": false, "description": "Latest valid time to include in the response.", "schema": { "type": "string", "minLength": 1, "description": "Latest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "min_forecast_hour", "in": "query", "required": false, "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "max_forecast_hour", "in": "query", "required": false, "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "type": "string", "minLength": 1, "description": "The initialization time for the forecast." }, "style": "form", "explode": true } ], "x-query-constraint": { "allOf": [ { "anyOf": [ { "not": { "required": [ "level" ] } }, { "required": [ "variable" ] } ] }, { "if": { "required": [ "include_distribution" ], "properties": { "include_distribution": { "const": true } } }, "then": { "required": [ "variable" ], "properties": { "variable": { "pattern": "^[^,]*[^\\s,][^,]*$" } } } } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Precipitation accumulation. The accumulation period depends on the model.", "x-unit": "mm" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" }, "p_type": { "type": [ "string", "null" ] }, "distribution": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "number", "null" ] }, "properties": { "mean": { "type": [ "number", "null" ], "description": "Ensemble mean. For `p_type`, the most probable precipitation-type code: 0 rain, 1 freezing rain, 2 ice pellets, 3 snow.", "x-available-on": [ "wm-6" ] }, "std": { "type": [ "number", "null" ], "description": "Ensemble standard deviation.", "x-available-on": [ "wm-6" ] }, "p01": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p05": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p10": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p25": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p75": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p90": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p95": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p99": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "gt_0p25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_2p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_6mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_12p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_50mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "p_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_freezing_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_ice_pellets": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_snow": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] } }, "description": "Ensemble distribution statistics for the variable.", "x-present-when": "`include_distribution=true`", "x-available-on": [ "wm-6" ] } }, "required": [ "time", "latitude", "longitude" ], "additionalProperties": { "type": [ "number", "string", "null" ], "description": "Value of the requested variable. `p_type` returns a precipitation-type name as a string; other variables return a number. Null when unavailable. Air temperature and dewpoint are returned in °C; skin and soil temperatures are returned in K." } } }, "description": "Forecasts, in the same order as the input coordinates." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Indices of requested coordinates excluded by geographic access rules.", "x-present-when": "requested coordinates are excluded" } }, "required": [ "forecasts", "initialization_time" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/point_forecast/interpolated_sounding": { "get": { "operationId": "get_interpolated_sounding", "summary": "Forecasted Sounding", "description": "Get interpolated vertical atmospheric profile forecasts for a specific coordinate.", "tags": [ "Models / Outputs" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/outputs/interpolated-sounding" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "coordinates", "in": "query", "required": true, "description": "A single latitude,longitude coordinate for the sounding location.", "schema": { "type": "string", "minLength": 1, "description": "A single latitude,longitude coordinate for the sounding location." }, "style": "form", "explode": true }, { "name": "time", "in": "query", "required": false, "description": "The time at which the forecast is valid. Alternatively, you can specify `initialization_time` and `forecast_hour`.", "schema": { "type": "string", "minLength": 1, "description": "The time at which the forecast is valid. Alternatively, you can specify `initialization_time` and `forecast_hour`." }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast. Use with `forecast_hour`, or with `time` to select a forecast from this model run.", "schema": { "type": "string", "minLength": 1, "description": "The initialization time for the forecast. Use with `forecast_hour`, or with `time` to select a forecast from this model run." }, "style": "form", "explode": true }, { "name": "forecast_hour", "in": "query", "required": false, "description": "Hours from `forecast_zero` for which to get the forecast. Use with `initialization_time`, or with `time` to restrict the forecast hour.", "schema": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "Hours from `forecast_zero` for which to get the forecast. Use with `initialization_time`, or with `time` to restrict the forecast hour.", "x-unit": "hours" }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "time" ] }, { "required": [ "initialization_time", "forecast_hour" ] } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "forecast_hour": { "type": "integer", "description": "Hours since `forecast_zero`. Valid time = `forecast_zero` + `forecast_hour`.", "x-unit": "hours" }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "data": { "type": "array", "items": { "type": "object", "properties": { "pressure_hpa": { "type": "integer", "description": "Atmospheric pressure.", "x-unit": "hPa" }, "altitude_m": { "type": "number", "description": "Altitude above mean sea level. Calculated from geopotential height.", "x-unit": "meters" }, "temperature_c": { "type": "number", "description": "Air temperature.", "x-unit": "°C" }, "dewpoint_c": { "type": "number", "description": "Dewpoint. Calculated from temperature and relative humidity.", "x-unit": "°C" }, "specific_humidity_kg_kg": { "type": "number", "description": "Specific humidity.", "x-unit": "kg/kg" }, "wind_u_ms": { "type": "number", "description": "Eastward wind component.", "x-unit": "m/s" }, "wind_v_ms": { "type": "number", "description": "Northward wind component.", "x-unit": "m/s" } }, "required": [ "pressure_hpa" ] }, "description": "Atmospheric data at different pressure levels." } }, "required": [ "initialization_time", "forecast_zero", "time", "forecast_hour", "latitude", "longitude", "data" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/models/v1/{model}/point_forecast/conditions": { "get": { "operationId": "get_point_forecast_conditions", "summary": "Conditions", "description": "Get ranked, human-readable conditions across a point forecast's full horizon.", "tags": [ "Models / Outputs" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/models/version_1/outputs/conditions" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "mm", "metamesh" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "coordinates", "in": "query", "required": true, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order.", "schema": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$", "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." }, "style": "form", "explode": true }, { "name": "hourly_interval", "in": "query", "required": false, "description": "Duration of each condition block in the `hourly` forecast.", "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 6, 8 ], "default": 1, "description": "Duration of each condition block in the `hourly` forecast.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "include_sky_state_icon", "in": "query", "required": false, "description": "Add `sky_state_icon_url` and `sky_state_condition` to every hourly, daily, and day/night block. Both fields are omitted when false.", "schema": { "type": "boolean", "default": false, "description": "Add `sky_state_icon_url` and `sky_state_condition` to every hourly, daily, and day/night block. Both fields are omitted when false." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Requested latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Requested longitude.", "x-unit": "degrees" }, "timezone": { "type": "string", "description": "Timezone used to calculate local daily and day/night boundaries." }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri", "description": "Absolute URL for an icon summarizing the block." }, "sky_state_icon_url": { "type": "string", "format": "uri", "description": "Additional cloud and precipitation icon.", "x-present-when": "`include_sky_state_icon=true`" }, "sky_state_condition": { "type": [ "string", "null" ], "description": "Highest-ranked cloud or precipitation condition used to select the additional icon, or null when none is available.", "x-present-when": "`include_sky_state_icon=true`" }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "Conditions, ordered from highest to lowest importance. Neutral states, such as calm wind, are omitted. Precipitation entries include their likelihood, such as `Low chance of drizzle`, unless precipitation is near certain, as in `Rain`." }, "start_time": { "type": "string", "format": "date-time", "description": "Inclusive start of the block." }, "end_time": { "type": "string", "format": "date-time", "description": "Exclusive end of the block." }, "text": { "type": "string", "description": "Plain-language paragraph describing conditions during the block." } }, "required": [ "icon_url", "conditions", "start_time", "end_time", "text" ] }, "description": "Condition blocks spanning the available forecast horizon at the requested `hourly_interval`." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri", "description": "Absolute URL for an icon summarizing the block." }, "sky_state_icon_url": { "type": "string", "format": "uri", "description": "Additional cloud and precipitation icon.", "x-present-when": "`include_sky_state_icon=true`" }, "sky_state_condition": { "type": [ "string", "null" ], "description": "Highest-ranked cloud or precipitation condition used to select the additional icon, or null when none is available.", "x-present-when": "`include_sky_state_icon=true`" }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "Conditions, ordered from highest to lowest importance. Neutral states, such as calm wind, are omitted. Precipitation entries include their likelihood, such as `Low chance of drizzle`, unless precipitation is near certain, as in `Rain`." }, "start_time": { "type": "string", "format": "date-time", "description": "Inclusive start of the block." }, "end_time": { "type": "string", "format": "date-time", "description": "Exclusive end of the block." }, "text": { "type": "string", "description": "Plain-language paragraph describing conditions during the block." } }, "required": [ "icon_url", "conditions", "start_time", "end_time", "text" ] }, "description": "Condition blocks grouped by the location's local calendar day." }, "day_night": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri", "description": "Absolute URL for an icon summarizing the block." }, "sky_state_icon_url": { "type": "string", "format": "uri", "description": "Additional cloud and precipitation icon.", "x-present-when": "`include_sky_state_icon=true`" }, "sky_state_condition": { "type": [ "string", "null" ], "description": "Highest-ranked cloud or precipitation condition used to select the additional icon, or null when none is available.", "x-present-when": "`include_sky_state_icon=true`" }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "Conditions, ordered from highest to lowest importance. Neutral states, such as calm wind, are omitted. Precipitation entries include their likelihood, such as `Low chance of drizzle`, unless precipitation is near certain, as in `Rain`." }, "start_time": { "type": "string", "format": "date-time", "description": "Inclusive start of the block." }, "end_time": { "type": "string", "format": "date-time", "description": "Exclusive end of the block." }, "text": { "type": "string", "description": "Plain-language paragraph describing conditions during the block." }, "period": { "type": "string", "enum": [ "day", "night" ], "description": "Whether the block covers daytime or nighttime." } }, "required": [ "icon_url", "conditions", "start_time", "end_time", "text", "period" ] }, "description": "Condition blocks grouped by local astronomical day and night periods." } }, "required": [ "latitude", "longitude", "timezone", "hourly", "daily", "day_night" ] }, "description": "Condition forecasts in the same order as the input coordinates." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of the first returned forecast point and the start of the first `hourly` block." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time. This can be later than `forecast_zero`." } }, "required": [ "forecasts", "forecast_zero", "initialization_time" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/custom-calculations/gridded": { "post": { "operationId": "calculate_gridded", "summary": "Gridded Calculation", "description": "Calculate a weather field and download the result as Zarr.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/custom-calculations/calculate" }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "wm-6", "wm-6-3km" ], "description": "Weather model to use." }, "initialization_time": { "type": [ "string", "null" ], "format": "date-time", "description": "The initialization time for the forecast." }, "calculation": { "type": "string", "minLength": 1, "description": "Calculation text describing the operation to run at each grid cell. See [About Custom Calculations](/weather/version_1/custom-calculations/about/) for syntax and examples." }, "forecast_hours": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 4294967295 }, { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 } } ], "description": "One forecast hour or a nonempty list of forecast hours. Omit to evaluate every available forecast hour.", "x-unit": "hours" }, "bounds": { "type": [ "object", "null" ], "properties": { "min_latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box. Provide with `max_latitude`; must be less than or equal to it." }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box. Provide with `min_latitude`." }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box. Provide with `max_longitude`. A western bound greater than the eastern bound selects across the dateline." }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box. Provide with `min_longitude`." } }, "allOf": [ { "anyOf": [ { "required": [ "min_latitude", "max_latitude" ] }, { "not": { "anyOf": [ { "required": [ "min_latitude" ] }, { "required": [ "max_latitude" ] } ] } } ] }, { "anyOf": [ { "required": [ "min_longitude", "max_longitude" ] }, { "not": { "anyOf": [ { "required": [ "min_longitude" ] }, { "required": [ "max_longitude" ] } ] } } ] } ], "additionalProperties": false, "description": "Geographic bounds for `wm-6`; omit for `wm-6-3km`. Each latitude or longitude pair is optional; omit a pair to return every coordinate on that axis." }, "as_url": { "type": "boolean", "default": false, "description": "If true, returns a JSON response with a temporary download URL instead of the file directly. The URL points to the generated Zarr ZIP archive and remains active for 30 minutes after the ZIP file is generated. The MCP requires `true` or omission." } }, "required": [ "model", "calculation" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response in the requested format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "url_expires_at": { "type": "string", "format": "date-time" }, "content_type": { "type": "string", "const": "application/zip" }, "size_bytes": { "type": "integer", "minimum": 0 } }, "required": [ "url", "url_expires_at", "content_type", "size_bytes" ] } }, "application/zip": { "schema": { "type": "string", "format": "binary", "x-archive-schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": [ "number", "null" ] } } } } }, "description": "The calculated float32 values. See the dimensions below." }, "forecast_hour": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "description": "The forecast hours included in `result`.", "x-unit": "hours" }, "ensemble_member": { "type": "array", "items": { "type": "integer" }, "description": "The ensemble member numbers represented by the separate calculated grids in the result.", "x-present-when": "members stay separate" }, "latitude": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } ], "description": "The location of the grid cells in `result`. Global grids use one-dimensional coordinate arrays; the 3 km grid uses two-dimensional coordinate arrays.", "x-unit": "degrees" }, "longitude": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } ], "description": "The location of the grid cells in `result`. Global grids use one-dimensional coordinate arrays; the 3 km grid uses two-dimensional coordinate arrays.", "x-unit": "degrees" }, "attributes": { "type": "object", "properties": { "model": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `initialization_time`." }, "forecast_hours": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "calculation": { "type": "string" }, "output_calculations": { "type": "array", "items": { "type": "string" }, "description": "The calculation used to produce each output grid." }, "forecast_hour_errors": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "forecast_hour", "code", "message" ] }, "description": "A list of skipped forecast hours. Each entry contains `forecast_hour`, `code`, and `message`." }, "evaluations": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "required": [ "forecast_hour" ] }, "description": "One entry for each successful forecast hour. Each entry contains `forecast_hour` and metadata describing the times, pressure levels, and ensemble members represented by that result." } }, "required": [ "model", "initialization_time", "forecast_zero", "forecast_hours", "calculation", "output_calculations", "forecast_hour_errors", "evaluations" ], "description": "The model, initialization time, calculation text, and exact forecast inputs used." } }, "required": [] } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/custom-calculations/points": { "post": { "operationId": "calculate_points", "summary": "Point Calculation", "description": "Calculate weather values at geographic coordinates and receive JSON.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/custom-calculations/points" }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "wm-6", "wm-6-3km" ], "description": "Weather model to use." }, "initialization_time": { "type": [ "string", "null" ], "format": "date-time", "description": "The initialization time for the forecast." }, "forecast_hours": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 4294967295 }, { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 } } ], "description": "One forecast hour or a nonempty list of forecast hours. Omit to evaluate every available forecast hour.", "x-unit": "hours" }, "calculation": { "type": "string", "minLength": 1, "description": "Custom calculation expression to evaluate. See [About Custom Calculations](/weather/version_1/custom-calculations/about/) for syntax and examples." }, "coordinates": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." } }, "required": [ "model", "calculation", "coordinates" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `initialization_time`." }, "forecast_hours": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "description": "The requested forecast hours, returned as an array.", "x-unit": "hours" }, "calculation": { "type": "string", "description": "The calculation evaluated by the request." }, "output_calculations": { "type": "array", "items": { "type": "string" }, "description": "The calculation for each output. `output_calculations[i]` describes `outputs[i]` in every successful forecast-hour result." }, "forecast_hour_errors": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "The forecast hour that could not be calculated.", "x-unit": "hours" }, "code": { "type": "string", "description": "Machine-readable reason for the failure." }, "message": { "type": "string", "description": "Human-readable description of the failure." } }, "required": [ "forecast_hour", "code", "message" ] }, "description": "Requested forecast hours that could not be calculated. Empty when every requested hour succeeds." }, "coordinates": { "type": "string", "description": "The requested latitude,longitude pairs in request order. Every `values` array follows this order." }, "results": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "The successfully calculated forecast hour.", "x-unit": "hours" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "valid_from": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the grid's valid time range." }, "valid_to": { "type": [ "string", "null" ], "format": "date-time", "description": "The end of the grid's valid time range." }, "values": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "One calculated value for each latitude,longitude pair in `coordinates`, in the same order. Unavailable, outside-grid, and non-finite values are `null`." } }, "required": [ "valid_from", "valid_to", "values" ] }, "description": "The calculated outputs, in the same order as `output_calculations`." } }, "required": [ "forecast_hour", "outputs" ] }, "description": "One result for each forecast hour that was calculated successfully." } }, "required": [ "model", "initialization_time", "forecast_zero", "forecast_hours", "calculation", "output_calculations", "forecast_hour_errors", "coordinates", "results" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/custom-calculations/threshold": { "post": { "operationId": "calculate_threshold", "summary": "Threshold Calculation", "description": "Return areas where a custom calculation meets a threshold.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/custom-calculations/threshold" }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "wm-6", "wm-6-3km" ], "description": "Weather model to use." }, "initialization_time": { "type": [ "string", "null" ], "format": "date-time", "description": "The initialization time for the forecast." }, "forecast_hours": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 4294967295 }, { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 } } ], "description": "One forecast hour or a nonempty list of forecast hours. Omit to evaluate every available forecast hour.", "x-unit": "hours" }, "calculation": { "type": "string", "minLength": 1, "description": "Custom calculation expression whose result will be thresholded. See [About Custom Calculations](/weather/version_1/custom-calculations/about/) for syntax and examples." }, "bounds": { "type": "object", "properties": { "min_latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box. Must be less than `max_latitude`." }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box." }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box. Must be less than `max_longitude`. The bounding box cannot cross the dateline." }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box." } }, "required": [ "min_latitude", "max_latitude", "min_longitude", "max_longitude" ], "x-propertyOrder": [ [ "min_latitude", "max_latitude" ], [ "min_longitude", "max_longitude" ] ], "additionalProperties": false, "description": "Bounding box used to calculate the threshold and clip the returned polygons." }, "threshold": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "absolute", "description": "Kind of threshold." }, "value": { "type": "number", "description": "Cutoff value. Required when `kind` is `absolute`." }, "comparison": { "type": "string", "enum": [ "at_or_above", "at_or_below" ], "description": "Side of the cutoff to select. Required when `kind` is `absolute`." } }, "required": [ "kind", "value", "comparison" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "percentile", "description": "Kind of threshold." }, "percentile": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage selected from the end named by `direction`. For the highest 10%, use `percentile: 10` and `direction: \"highest\"`. Required when `kind` is `percentile`." }, "direction": { "type": "string", "enum": [ "lowest", "highest" ], "description": "End of the distribution to select from. Required when `kind` is `percentile`." } }, "required": [ "kind", "percentile", "direction" ], "additionalProperties": false } ], "description": "An absolute or percentile threshold." } }, "required": [ "model", "calculation", "bounds", "threshold" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/geo+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection", "description": "GeoJSON collection type." }, "model": { "type": "string", "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `initialization_time`." }, "forecast_hours": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "description": "The requested forecast hours, returned as an array.", "x-unit": "hours" }, "calculation": { "type": "string", "description": "The calculation evaluated by the request." }, "output_calculations": { "type": "array", "items": { "type": "string" }, "description": "The calculation for each output. Each feature repeats its matching calculation in `properties.output_calculation`." }, "forecast_hour_errors": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "The forecast hour that could not be calculated.", "x-unit": "hours" }, "code": { "type": "string", "description": "Machine-readable reason for the failure." }, "message": { "type": "string", "description": "Human-readable description of the failure." } }, "required": [ "forecast_hour", "code", "message" ] }, "description": "Requested forecast hours that could not be calculated. Empty when every requested hour succeeds." }, "threshold": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "absolute" }, "value": { "type": "number" }, "comparison": { "type": "string", "enum": [ "at_or_above", "at_or_below" ] } }, "required": [ "kind", "value", "comparison" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "percentile" }, "percentile": { "type": "number", "exclusiveMinimum": 0, "maximum": 100, "description": "Percentage selected from the end named by direction. For the top 10%, use percentile 10 with direction highest; its cutoff is the 90th percentile." }, "direction": { "type": "string", "enum": [ "lowest", "highest" ], "description": "Select the lowest or highest percentile percent of finite calculated values inside bounds. Values equal to the cutoff are included." } }, "required": [ "kind", "percentile", "direction" ], "additionalProperties": false } ], "description": "Threshold supplied in the request." }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature", "description": "Always `Feature`." }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "WGS84 geometry using `[longitude, latitude]` coordinates." }, "properties": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295, "description": "The successfully calculated forecast hour.", "x-unit": "hours" }, "output_calculation": { "type": "string", "description": "The calculation used to produce this output grid." }, "valid_from": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the grid's valid time range." }, "valid_to": { "type": [ "string", "null" ], "format": "date-time", "description": "The end of the grid's valid time range." } }, "required": [ "forecast_hour", "output_calculation", "valid_from", "valid_to" ], "description": "Forecast-hour, output-grid, and validity metadata for the feature." } }, "required": [ "type", "geometry", "properties" ] }, "description": "One feature for each output grid that contains matching cells." } }, "required": [ "type", "model", "initialization_time", "forecast_zero", "forecast_hours", "calculation", "output_calculations", "forecast_hour_errors", "threshold", "features" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/degree_days/{model}/cdds": { "get": { "operationId": "get_cdd", "summary": "Population Weighted CDDs", "description": "Population‑weighted Cooling Degree Days (CDD) forecasts for US states.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/degree-days/cdd" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "wm-4.5-ens-mean", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "gefs" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "type": "string", "format": "date-time", "description": "The initialization time for the forecast." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ], "description": "CDD value for the state and local date; null when forecast data is unavailable.", "x-unit": "°F degree days" }, "description": "Keyed by state name, with CDD values for that date." }, "description": "CDD values keyed by local calendar date; each date maps to a state-to-value object." }, "dates": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "Forecast dates, based on local time within each state. Boundary dates can have only null values when local forecast data is unavailable." }, "metadata": { "type": "object", "properties": { "model": { "type": "string", "description": "Model name." }, "subset": { "type": "string", "description": "Forecast subset identifier." }, "initialization_time": { "type": "string", "format": "date-time", "description": "Initialization time of the calculation." } }, "required": [ "model", "subset", "initialization_time" ], "description": "Forecast calculation metadata." } }, "required": [ "cdd", "dates", "metadata" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/climatology/point": { "get": { "operationId": "get_climatology", "summary": "Climatology", "description": "Look up typical weather for each hour at one or more locations.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/climatology/climatology" }, "parameters": [ { "name": "time", "in": "query", "required": false, "description": "Retrieve one hour. Use this alone, or provide both range parameters instead. Must be hour-aligned.", "schema": { "type": "string", "format": "date-time", "description": "Retrieve one hour. Use this alone, or provide both range parameters instead. Must be hour-aligned." }, "style": "form", "explode": true }, { "name": "min_time", "in": "query", "required": false, "description": "First hour in an inclusive range. Requires `max_time` and cannot be combined with `time`.", "schema": { "type": "string", "format": "date-time", "description": "First hour in an inclusive range. Requires `max_time` and cannot be combined with `time`." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Last hour in an inclusive range. Returns up to 8,784 hourly timestamps.", "schema": { "type": "string", "format": "date-time", "description": "Last hour in an inclusive range. Returns up to 8,784 hourly timestamps." }, "style": "form", "explode": true }, { "name": "coordinates", "in": "query", "required": true, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order.", "schema": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." }, "style": "form", "explode": true }, { "name": "normal", "in": "query", "required": false, "description": "Normal period to use.", "schema": { "type": "string", "enum": [ "1991-2020", "2011-2020", "2016-2025" ], "default": "1991-2020", "description": "Normal period to use." }, "style": "form", "explode": true }, { "name": "rolling_average_days", "in": "query", "required": false, "description": "Takes a mean of the requested date + this many days on either side for a smoother climatology. For example, if `rolling_average_days` is set to `3` and the requested date is August 15th, this will be the average of the requested time of day from August 12th through 18th.", "schema": { "type": "integer", "minimum": 0, "maximum": 182, "default": 0, "description": "Takes a mean of the requested date + this many days on either side for a smoother climatology. For example, if `rolling_average_days` is set to `3` and the requested date is August 15th, this will be the average of the requested time of day from August 12th through 18th.", "x-unit": "days" }, "style": "form", "explode": true }, { "name": "elevation_correction", "in": "query", "required": false, "description": "Elevation-correct temperature and dewpoint.", "schema": { "type": "boolean", "default": false, "description": "Elevation-correct temperature and dewpoint." }, "style": "form", "explode": true }, { "name": "water_strategy", "in": "query", "required": false, "description": "Set to `allow` to use water grid cells. By default, interpolation prefers land cells at land locations.", "schema": { "type": "string", "description": "Set to `allow` to use water grid cells. By default, interpolation prefers land cells at land locations." }, "style": "form", "explode": true } ], "x-query-constraint": { "oneOf": [ { "required": [ "time" ], "not": { "anyOf": [ { "required": [ "min_time" ] }, { "required": [ "max_time" ] } ] } }, { "required": [ "min_time", "max_time" ], "not": { "required": [ "time" ] } } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "normal": { "type": "string", "description": "The normal period used." }, "time": { "type": "string", "format": "date-time", "description": "The requested hour.", "x-present-when": "you sent `time`" }, "start_time": { "type": "string", "format": "date-time", "description": "The first returned hour.", "x-present-when": "you sent a range" }, "end_time": { "type": "string", "format": "date-time", "description": "The last returned hour.", "x-present-when": "you sent a range" }, "rolling_average_days": { "type": "integer", "minimum": 0, "maximum": 182, "description": "Days averaged on each side of a requested date.", "x-unit": "days" }, "climatologies": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "The requested timestamp for the climatology point." }, "latitude": { "type": "number", "description": "The requested latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "The requested longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Climatological air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Climatological dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Average precipitation total for the preceding hour. For rain from 09:00 to 10:00 UTC, request 10:00 UTC.", "x-unit": "mm" }, "pressure_msl": { "type": "null", "description": "Reserved mean sea-level pressure field. The current climatology dataset does not provide this value.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" } }, "required": [ "time", "latitude", "longitude", "temperature_2m", "dewpoint_2m", "precipitation", "pressure_msl", "wind_u_10m", "wind_v_10m", "wind_speed_10m", "wind_u_100m", "wind_v_100m", "wind_speed_100m" ] } }, "description": "One hourly series per accepted coordinate, in request order." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 } } }, "required": [ "normal", "rolling_average_days", "climatologies" ], "oneOf": [ { "required": [ "time" ], "not": { "anyOf": [ { "required": [ "start_time" ] }, { "required": [ "end_time" ] } ] } }, { "required": [ "start_time", "end_time" ], "not": { "required": [ "time" ] } } ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/climatology/summary": { "get": { "operationId": "get_climatology_summary", "summary": "Climatology Summary", "description": "Look up typical daily highs, lows, precipitation, and wind at one or more locations.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/climatology/climatology-summary" }, "parameters": [ { "name": "date", "in": "query", "required": false, "description": "One calendar date. Requires `group_by=day` (the default); do not combine it with a date range.", "schema": { "type": "string", "format": "date", "description": "One calendar date. Requires `group_by=day` (the default); do not combine it with a date range." }, "style": "form", "explode": true }, { "name": "start_date", "in": "query", "required": false, "description": "First date in an inclusive range. Requires `end_date`; the range can return daily or grouped rows.", "schema": { "type": "string", "format": "date", "description": "First date in an inclusive range. Requires `end_date`; the range can return daily or grouped rows." }, "style": "form", "explode": true }, { "name": "end_date", "in": "query", "required": false, "description": "Last date in an inclusive range. The range can contain at most 366 dates.", "schema": { "type": "string", "format": "date", "description": "Last date in an inclusive range. The range can contain at most 366 dates." }, "style": "form", "explode": true }, { "name": "coordinates", "in": "query", "required": true, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order.", "schema": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." }, "style": "form", "explode": true }, { "name": "group_by", "in": "query", "required": false, "description": "`day`: one row per date. `week`: consecutive seven-day groups starting at `start_date`. `month`: calendar months. `period`: one row for the full range. First and last weeks or months include only requested dates.", "schema": { "type": "string", "enum": [ "day", "week", "month", "period" ], "default": "day", "description": "`day`: one row per date. `week`: consecutive seven-day groups starting at `start_date`. `month`: calendar months. `period`: one row for the full range. First and last weeks or months include only requested dates." }, "style": "form", "explode": true }, { "name": "normal", "in": "query", "required": false, "description": "Normal period to use.", "schema": { "type": "string", "enum": [ "1991-2020", "2011-2020", "2016-2025" ], "default": "1991-2020", "description": "Normal period to use." }, "style": "form", "explode": true }, { "name": "elevation_correction", "in": "query", "required": false, "description": "Elevation-correct temperature and dewpoint.", "schema": { "type": "boolean", "default": false, "description": "Elevation-correct temperature and dewpoint." }, "style": "form", "explode": true }, { "name": "water_strategy", "in": "query", "required": false, "description": "Set to `allow` to use water grid cells. By default, interpolation prefers land cells at land locations.", "schema": { "type": "string", "description": "Set to `allow` to use water grid cells. By default, interpolation prefers land cells at land locations." }, "style": "form", "explode": true } ], "x-query-constraint": { "oneOf": [ { "required": [ "date" ], "properties": { "group_by": { "const": "day" } }, "not": { "anyOf": [ { "required": [ "start_date" ] }, { "required": [ "end_date" ] } ] } }, { "required": [ "start_date", "end_date" ], "not": { "required": [ "date" ] } } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "normal": { "type": "string", "description": "The normal period used." }, "group_by": { "type": "string", "enum": [ "day", "week", "month", "period" ], "description": "The selected grouping." }, "start_date": { "type": "string", "format": "date", "description": "First requested date." }, "end_date": { "type": "string", "format": "date", "description": "Last requested date." }, "climatology_summaries": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Inclusive dates covered by this row." }, "end_date": { "type": "string", "format": "date", "description": "Inclusive dates covered by this row." }, "latitude": { "type": "number", "description": "Requested coordinate, rounded to two decimal places.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Requested coordinate, rounded to two decimal places.", "x-unit": "degrees" }, "standard_utc_offset_minutes": { "type": "integer", "description": "Fixed local standard time offset from UTC; daylight saving time is not applied.", "x-unit": "minutes" }, "temperature_2m_min": { "type": [ "number", "null" ], "description": "Mean daily minimum and mean daily maximum air temperature.", "x-unit": "°C" }, "temperature_2m_max": { "type": [ "number", "null" ], "description": "Mean daily minimum and mean daily maximum air temperature.", "x-unit": "°C" }, "dewpoint_2m_min": { "type": [ "number", "null" ], "description": "Mean daily minimum and mean daily maximum dewpoint.", "x-unit": "°C" }, "dewpoint_2m_max": { "type": [ "number", "null" ], "description": "Mean daily minimum and mean daily maximum dewpoint.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Sum of daily normal precipitation over this row's dates.", "x-unit": "mm" }, "avg_daily_precipitation": { "type": [ "number", "null" ], "description": "Mean daily normal precipitation over this row's dates.", "x-unit": "mm/day" }, "wind_speed_10m_mean": { "type": [ "number", "null" ], "description": "Averages of each day's mean and maximum wind speed at 10 meters.", "x-unit": "m/s" }, "wind_speed_10m_max": { "type": [ "number", "null" ], "description": "Averages of each day's mean and maximum wind speed at 10 meters.", "x-unit": "m/s" } }, "required": [ "start_date", "end_date", "latitude", "longitude", "standard_utc_offset_minutes", "temperature_2m_min", "temperature_2m_max", "dewpoint_2m_min", "dewpoint_2m_max", "precipitation", "avg_daily_precipitation", "wind_speed_10m_mean", "wind_speed_10m_max" ] } }, "description": "One array of summary rows per accepted coordinate, in request order." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 } } }, "required": [ "normal", "group_by", "start_date", "end_date", "climatology_summaries" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/for_location": { "get": { "operationId": "get_event_context", "summary": "Event Context", "description": "Events affecting requested coordinates at each forecast time.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/event-context" }, "parameters": [ { "name": "coordinates", "in": "query", "required": true, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order.", "schema": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "pattern": "^[^;]+(?:;[^;]+){0,9}$", "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" }, { "type": "string", "const": "latest" } ], "description": "The initialization time for the forecast." }, "style": "form", "explode": true }, { "name": "min_forecast_time", "in": "query", "required": false, "description": "Earliest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Earliest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "max_forecast_time", "in": "query", "required": false, "description": "Latest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Latest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "event_type", "in": "query", "required": false, "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Omit to include all supported types.", "schema": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Omit to include all supported types." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `initialization_time`." }, "events": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Requested latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Requested longitude.", "x-unit": "degrees" }, "time": { "type": "string", "format": "date-time", "description": "Forecast time represented by this row." }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event." }, "forecast_hour": { "type": "integer", "description": "Hours from `forecast_zero` to this record's `valid_time`.", "x-unit": "hours" }, "valid_time": { "type": "string", "format": "date-time", "description": "Time of the atmospheric-river footprint or front boundary, or start of a heatwave or coldwave UTC map interval." }, "period_end": { "type": "string", "format": "date-time", "description": "Exclusive end of a heatwave or coldwave map interval; three hours after `valid_time` by default. Omitted for atmospheric rivers and fronts." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Overall geometry's summary for this forecast hour. Polygon events include severity, centers, area, and intensity metrics; fronts include classifications and `length_km`. Matches `properties.summary` on the overall geometry in [Event Detail](/weather/version_1/events/event-detail/)." } }, "required": [ "event_type", "forecast_hour", "valid_time", "summary" ], "description": "One matching event, keyed by its public ID." }, "description": "Keyed by `event_id`. Includes polygon events containing the coordinate and fronts whose swept area crosses it during an adjacent forecast interval." } }, "required": [ "latitude", "longitude", "time", "events" ], "description": "One row at a forecast time, ordered chronologically." }, "description": "Forecast-time rows for one requested coordinate." }, "description": "One array per requested coordinate, in request order. Each contains rows ordered by time: `events[coordinate_index][time_index]`." } }, "required": [ "model", "initialization_time", "forecast_zero", "events" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/{event_type}/{event_id}/details": { "get": { "operationId": "get_event_detail", "summary": "Event Detail", "description": "One event's forecast from one model initialization, as JSON or GeoJSON.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/event-detail" }, "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Must match the event ID prefix." }, "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Must match the event ID prefix." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID linking forecasts of the same weather event across model runs. Returned by [Index Events](/weather/version_1/events/events-index/) or [Event](/weather/version_1/events/events/)." }, "description": "ID linking forecasts of the same weather event across model runs. Returned by [Index Events](/weather/version_1/events/events-index/) or [Event](/weather/version_1/events/events/)." }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" }, { "type": "string", "const": "latest" } ], "description": "The initialization time for the forecast." }, "style": "form", "explode": true }, { "name": "format", "in": "query", "required": false, "description": "Response format.", "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json", "description": "Response format." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response in the requested format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model whose forecast output was used." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event." }, "init_time": { "type": "string", "format": "date-time", "description": "Selected initialization." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `init_time`." }, "event_id": { "type": "string", "description": "Persistent public ID across matched forecasts. See [About Weather Events](/weather/version_1/events/about/) for ID conventions." }, "start_time": { "type": "string", "format": "date-time", "description": "First represented forecast sample." }, "end_time": { "type": "string", "format": "date-time", "description": "Last AR/front sample time or exclusive end of the last heat/cold frame." }, "lineage": { "type": "object", "properties": { "parents": { "type": "array", "items": { "type": "string" }, "description": "Events this event split from or merged into." }, "children": { "type": "array", "items": { "type": "string" }, "description": "Events that split from this event or merged into it." } }, "required": [ "parents", "children" ], "description": "Direct relationships from this initialization only; arrays contain unique public event IDs." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ], "description": "Polygon events: highest represented category. For ARs, this is duration-adjusted AR1–AR5, not the highest instantaneous IVT contour." }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Polygon geometric center, WGS84 `[longitude, latitude]`; null if undefined." }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Polygon intensity-weighted center, WGS84 `[longitude, latitude]`; null if undefined." }, "max_area_km2": { "type": "number", "description": "Polygon events: largest area at one represented step.", "x-unit": "km²" }, "total_area_km2": { "type": "number", "description": "Polygon events: sampled union area, counting overlapping ground once.", "x-unit": "km²" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number", "description": "Atmospheric rivers: maximum IVT.", "x-unit": "kg m⁻¹ s⁻¹" }, "max_temp_c": { "type": "number", "description": "Heatwaves: maximum qualifying daily Tmax.", "x-unit": "°C" }, "min_tmin_c": { "type": "number", "description": "Coldwaves: lowest daily Tmin.", "x-unit": "°C" }, "max_threshold_deficit_c": { "type": "number", "description": "Coldwaves: largest local P15 minus Tmin deficit.", "x-unit": "°C" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "description": "Fronts: sorted, unique classifications in this run." }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number", "description": "Fronts: greatest length at one represented step, rounded to two decimals.", "x-unit": "km" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Event-wide overall summary, repeated at `geometries[0].properties.summary`." }, "geometries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature", "description": "Always `Feature`." }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "WGS84 `[longitude, latitude]` MultiPolygon for polygon events; MultiLineString for fronts, including one-part lines." }, "properties": { "type": "object", "properties": { "name": { "type": "string", "description": "`overall_geometry` or `severity_region_N`. N is fixed: AR1–AR5 → 1–5; heat P85/P90/P95/P98 and cold P15/P10/P5/P2 → 1–4." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number", "description": "Severity region's largest area at one step.", "x-unit": "km²" }, "total_area_km2": { "type": "number", "description": "Severity region's sampled union area.", "x-unit": "km²" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string", "description": "Event-wide polygon severity region's minimum included category; duration-adjusted for ARs." }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time", "description": "First occurrence of this severity." }, "end_time": { "type": "string", "format": "date-time", "description": "Last AR occurrence or exclusive heat/cold period end. Bounds can span gaps." }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Overall: same as root `summary`. Severity region: fields below, scoped to that cumulative tier." } }, "required": [ "name", "summary" ], "description": "Geometry name and its own summary." } }, "required": [ "type", "geometry", "properties" ] }, "description": "Event-wide geometry: overall first, then nonempty cumulative polygon severity regions. Fronts have one overall line Feature." }, "forecast_hours": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "description": "Hours since `forecast_zero`.", "x-unit": "hours" }, "valid_time": { "type": "string", "format": "date-time", "description": "Sample time or heat/cold map-frame start." }, "period_end": { "type": "string", "format": "date-time", "description": "Heat/cold only: exclusive map-frame end; three hours later by default, 24 hours for the UTC-day alternative." }, "geometries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature", "description": "Always `Feature`." }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "WGS84 `[longitude, latitude]` MultiPolygon for polygon events; MultiLineString for fronts." }, "properties": { "type": "object", "properties": { "name": { "type": "string", "description": "`overall_geometry`, `severity_region_N`, `cold_front`, `warm_front`, `stationary_front`, or `occluded_front`." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ], "description": "Polygon overall: strongest category at this step. AR1–AR5 remains duration-adjusted and does not cap the instantaneous IVT contours." }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Polygon overall geometric center, WGS84 `[longitude, latitude]`." }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Polygon overall intensity-weighted center, WGS84 `[longitude, latitude]`." }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number", "description": "Current area of a polygon overall or nested contour region.", "x-unit": "km²" }, "max_ivt": { "type": "number", "description": "Polygon overall: same event-specific intensity keys and units as the root `summary`, scoped to this step." }, "max_temp_c": { "type": "number", "description": "Polygon overall: same event-specific intensity keys and units as the root `summary`, scoped to this step." }, "min_tmin_c": { "type": "number", "description": "Polygon overall: same event-specific intensity keys and units as the root `summary`, scoped to this step." }, "max_threshold_deficit_c": { "type": "number", "description": "Polygon overall: same event-specific intensity keys and units as the root `summary`, scoped to this step." }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "description": "Front overall: sorted, unique classifications at this step." }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ], "description": "Front section classification." }, "max_length_km": { "type": "number" }, "length_km": { "type": "number", "description": "Front overall or section length, rounded to two decimals.", "x-unit": "km" }, "severity": { "type": "string", "description": "Heat/cold forecast-hour severity region's minimum included category. AR forecast-hour contours use `instantaneous_severity` instead." }, "instantaneous_severity": { "type": "string", "description": "AR forecast-hour contour only: AR1–AR5 maps to IVT ≥250, ≥500, ≥750, ≥1,000, ≥1,250 kg m⁻¹ s⁻¹, respectively, without a duration adjustment. An AR3 event can contain an instantaneous AR4 contour." }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] }, "description": "Front section only: one `left` or `right` per MultiLineString coordinate part, in the same order; never null. Relative to walking the part from its first coordinate to its last." }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number", "description": "Mean classification probability." }, "max_probability": { "type": "number", "description": "Maximum classification probability." } }, "required": [ "mean_probability", "max_probability" ], "description": "Front section's classifier outputs, not calibrated event probabilities." } }, "required": [], "description": "Overall polygon: intensity, centers, and current area. Severity region: category and current area. Front overall: classes and length; section: class, length, and diagnostics." } }, "required": [ "name", "summary" ], "description": "Geometry name and summary for this step." } }, "required": [ "type", "geometry", "properties" ] }, "description": "Overall first; then nonempty polygon severity regions or present front sections in cold, warm, stationary, occluded order. Render classified front sections alone to avoid drawing the overall line twice." } }, "required": [ "forecast_hour", "valid_time", "geometries" ] }, "description": "Represented steps, ordered by `valid_time`; always populated in Event Detail." } }, "required": [ "model", "event_type", "init_time", "forecast_zero", "event_id", "start_time", "end_time", "lineage", "summary", "geometries", "forecast_hours" ] } }, "application/geo+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection", "description": "GeoJSON collection type." }, "model": { "type": "string", "description": "Model whose forecast output was used." }, "init_time": { "type": "string", "format": "date-time", "description": "Selected initialization." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "total": { "type": "integer", "description": "Number of events; always 1." }, "start_time": { "type": "string", "format": "date-time", "description": "First represented forecast sample." }, "end_time": { "type": "string", "format": "date-time", "description": "Last AR/front sample time or exclusive end of the last heat/cold frame." }, "lineage": { "type": "object", "properties": { "parents": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "string" } } }, "required": [ "parents", "children" ], "description": "Parent and child events related to this event in the selected model run." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Event-wide statistics, such as peak severity, affected area, or front length." }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature", "description": "Always `Feature`." }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "WGS84 `[longitude, latitude]` MultiPolygon for polygon events; MultiLineString for fronts." }, "properties": { "type": "object", "properties": { "event_id": { "type": "string", "description": "ID of the weather event represented by this feature." }, "name": { "type": "string", "description": "`overall_geometry`, `severity_region_N`, or a forecast-hour front section: `cold_front`, `warm_front`, `stationary_front`, `occluded_front`." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Summary statistics for this feature’s geometry." }, "forecast_hour": { "type": "integer", "description": "Forecast hour and corresponding valid time for this geometry. Present for forecast-hour features." }, "valid_time": { "type": "string", "format": "date-time", "description": "Forecast hour and corresponding valid time for this geometry. Present for forecast-hour features." }, "period_end": { "type": "string", "format": "date-time", "description": "End of the forecast period represented by this geometry, exclusive. Present for heatwave and coldwave forecast-hour features." }, "model": { "type": "string", "description": "Selected model, event type, and initialization." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Selected model, event type, and initialization." }, "init_time": { "type": "string", "format": "date-time", "description": "Selected model, event type, and initialization." } }, "required": [ "event_id", "model", "event_type", "init_time", "name", "summary" ], "description": "Information describing this feature, including its event ID, geometry name, and summary statistics." } }, "required": [ "type", "geometry", "properties" ] }, "description": "Geographic shapes covering the event’s full forecast and individual forecast hours: polygons for affected areas and lines for fronts." } }, "required": [ "type", "model", "init_time", "forecast_zero", "total", "start_time", "end_time", "lineage", "summary", "features" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/{event_type}/{event_id}/initialization_times": { "get": { "operationId": "get_event_init_times", "summary": "Initialization Times for Event", "description": "List published model runs containing one event.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/event-init-times" }, "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Must match the event ID prefix." }, "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts. Must match the event ID prefix." }, { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID linking forecasts of the same weather event across model runs. Returned by [Event](/weather/version_1/events/events/) or [Index Events](/weather/version_1/events/events-index/)." }, "description": "ID linking forecasts of the same weather event across model runs. Returned by [Event](/weather/version_1/events/events/) or [Index Events](/weather/version_1/events/events-index/)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Requested event ID." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of the requested event." }, "model": { "type": "string", "description": "Model whose forecast output was used." }, "available": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times, sorted earliest to latest." }, "latest": { "type": "string", "format": "date-time", "description": "Latest available initialization; the default for Event Detail." } }, "required": [ "event_id", "event_type", "model", "available", "latest" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/{event_type}": { "get": { "operationId": "get_events", "summary": "Event", "description": "Events of a selected type from one model initialization.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/events" }, "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts." }, "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts." }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" }, { "type": "string", "const": "latest" } ], "description": "The initialization time for the forecast." }, "style": "form", "explode": true }, { "name": "include_details", "in": "query", "required": false, "description": "Include forecast-hour geometries and their summaries.", "schema": { "type": "boolean", "default": false, "description": "Include forecast-hour geometries and their summaries." }, "style": "form", "explode": true }, { "name": "format", "in": "query", "required": false, "description": "Response format.", "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json", "description": "Response format." }, "style": "form", "explode": true }, { "name": "min_latitude", "in": "query", "required": false, "description": "Southern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_latitude", "in": "query", "required": false, "description": "Northern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "min_longitude", "in": "query", "required": false, "description": "Western edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_longitude", "in": "query", "required": false, "description": "Eastern edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box." }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "min_latitude", "max_latitude", "min_longitude", "max_longitude" ] }, { "not": { "anyOf": [ { "required": [ "min_latitude" ] }, { "required": [ "max_latitude" ] }, { "required": [ "min_longitude" ] }, { "required": [ "max_longitude" ] } ] } } ] }, "responses": { "200": { "description": "Successful response in the requested format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model whose forecast output was used." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Requested event type, shared by all returned events." }, "init_time": { "type": "string", "format": "date-time", "description": "Selected initialization." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0. It can differ from `init_time`." }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_id": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "lineage": { "type": "object", "properties": { "parents": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "string" } } }, "required": [ "parents", "children" ], "description": "Parent and child event IDs within this initialization. See [Event Detail](/weather/version_1/events/event-detail/)." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Identical to `geometries[0].properties.summary`. Polygon events include peak severity, centers, areas, and event-specific metrics; fronts include classifications and `max_length_km`." }, "geometries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "properties": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [] } }, "required": [ "name", "summary" ] } }, "required": [ "type", "geometry", "properties" ] } }, "forecast_hours": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer" }, "valid_time": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "geometries": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "properties": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [] } }, "required": [ "name", "summary" ] } }, "required": [ "type", "geometry", "properties" ] } } }, "required": [ "forecast_hour", "valid_time", "geometries" ] } } }, "required": [ "event_id", "start_time", "end_time", "lineage", "summary", "geometries", "forecast_hours" ] }, "description": "Keyed by `event_id`. Each entry contains `event_id`, `start_time`, `end_time`, `lineage`, `summary`, `geometries`, and `forecast_hours`. Geometry and forecast-hour fields follow [Event Detail](/weather/version_1/events/event-detail/); `forecast_hours` is populated when `include_details=true`." }, "total": { "type": "integer", "description": "Number of weather events returned. In GeoJSON this counts events, not Features." } }, "required": [ "model", "event_type", "init_time", "forecast_zero", "events", "total" ] } }, "application/geo+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection", "description": "GeoJSON collection type." }, "model": { "type": "string", "description": "Model whose forecast output was used." }, "init_time": { "type": "string", "format": "date-time", "description": "Selected initialization." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "total": { "type": "integer", "description": "Number of weather events returned." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event." }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "lineage": { "type": "object", "properties": { "parents": { "type": "array", "items": { "type": "string" } }, "children": { "type": "array", "items": { "type": "string" } } }, "required": [ "parents", "children" ] }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [] } }, "required": [ "start_time", "end_time", "lineage", "summary" ] }, "description": "Summary information for each returned weather event, keyed by event ID. Includes its start and end times, relationships to other events, and summary statistics." }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature", "description": "Always `Feature`." }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "WGS84 `[longitude, latitude]` MultiPolygon for polygon events; MultiLineString for fronts." }, "properties": { "type": "object", "properties": { "event_id": { "type": "string", "description": "ID of the weather event represented by this feature." }, "name": { "type": "string", "description": "`overall_geometry`, `severity_region_N`, or a forecast-hour front section: `cold_front`, `warm_front`, `stationary_front`, `occluded_front`." }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [], "description": "Summary statistics for this feature’s geometry." }, "forecast_hour": { "type": "integer", "description": "Forecast hour and corresponding valid time for this geometry. Present for forecast-hour features." }, "valid_time": { "type": "string", "format": "date-time", "description": "Forecast hour and corresponding valid time for this geometry. Present for forecast-hour features." }, "period_end": { "type": "string", "format": "date-time", "description": "End of the forecast period represented by this geometry, exclusive. Present for heatwave and coldwave forecast-hour features." } }, "required": [ "event_id", "name", "summary" ], "description": "Information describing this feature, including its event ID, geometry name, and summary statistics." } }, "required": [ "type", "geometry", "properties" ] }, "description": "Geographic shapes of the returned events: polygons for affected areas and lines for fronts. Each feature includes its event ID and summary." } }, "required": [ "type", "model", "init_time", "forecast_zero", "total", "event_type", "events", "features" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/{event_type}/index": { "get": { "operationId": "get_events_index", "summary": "Index Events", "description": "Browse events of a selected type across model initializations.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/events-index" }, "parameters": [ { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts." }, "description": "Type of weather event. The `front` type includes cold, warm, stationary, and occluded fronts." }, { "name": "min_time", "in": "query", "required": false, "description": "Include events with a published forecast ending at or after this time.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" } ], "description": "Include events with a published forecast ending at or after this time." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Include events with a published forecast starting at or before this time.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" } ], "description": "Include events with a published forecast starting at or before this time." }, "style": "form", "explode": true }, { "name": "min_latitude", "in": "query", "required": false, "description": "Southern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Southern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_latitude", "in": "query", "required": false, "description": "Northern edge of the bounding box.", "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Northern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "min_longitude", "in": "query", "required": false, "description": "Western edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Western edge of the bounding box." }, "style": "form", "explode": true }, { "name": "max_longitude", "in": "query", "required": false, "description": "Eastern edge of the bounding box.", "schema": { "type": "number", "minimum": -180, "maximum": 180, "description": "Eastern edge of the bounding box." }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number.", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-indexed page number." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 64, "description": "Number of results per page." }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "min_latitude", "max_latitude", "min_longitude", "max_longitude" ] }, { "not": { "anyOf": [ { "required": [ "min_latitude" ] }, { "required": [ "max_latitude" ] }, { "required": [ "min_longitude" ] }, { "required": [ "max_longitude" ] } ] } } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model whose forecast output was used." }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_id": { "type": "string", "description": "ID linking forecasts of the same weather event across model runs." }, "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "Requested event type." }, "start_time": { "type": "string", "format": "date-time", "description": "Earliest forecast start across this event's published runs." }, "end_time": { "type": "string", "format": "date-time", "description": "Latest forecast end across this event's published runs." }, "latest_init_time": { "type": "string", "format": "date-time", "description": "Most recent initialization containing this event." } }, "required": [ "event_id", "event_type", "start_time", "end_time", "latest_init_time" ] }, "description": "Catalog entries keyed by `event_id`." }, "total": { "type": "integer", "description": "Distinct events matching all filters, counted before pagination." }, "page": { "type": "integer", "description": "Current page number." }, "page_size": { "type": "integer", "description": "Number of results per page." } }, "required": [ "model", "events", "total", "page", "page_size" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/degree_days/{model}/hdds": { "get": { "operationId": "get_hdd", "summary": "Population Weighted HDDs", "description": "Population‑weighted Heating Degree Days (HDD) forecasts for US states.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/degree-days/hdd" }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "wm-6", "wm-6-3km", "wm-4.5-ens-mean", "ecmwf-det", "ecmwf-ens", "aifs", "gfs", "gefs" ], "description": "Weather model to use." }, "description": "Weather model to use." }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "type": "string", "format": "date-time", "description": "The initialization time for the forecast." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ], "description": "HDD value for the state and local date; null when forecast data is unavailable.", "x-unit": "°F degree days" }, "description": "Keyed by state name, with HDD values for that date." }, "description": "HDD values keyed by local calendar date; each date maps to a state-to-value object." }, "dates": { "type": "array", "items": { "type": "string", "format": "date" }, "description": "Forecast dates, based on local time within each state. Boundary dates can have only null values when local forecast data is unavailable." }, "metadata": { "type": "object", "properties": { "model": { "type": "string", "description": "Model name." }, "subset": { "type": "string", "description": "Forecast subset identifier." }, "initialization_time": { "type": "string", "format": "date-time", "description": "Initialization time of the calculation." } }, "required": [ "model", "subset", "initialization_time" ], "description": "Forecast calculation metadata." } }, "required": [ "hdd", "dates", "metadata" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/point": { "get": { "operationId": "get_point_forecast", "summary": "Point Forecast", "description": "Get the forecasts for specific coordinates", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/point/point-forecast" }, "parameters": [ { "name": "coordinates", "in": "query", "required": false, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order.", "schema": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order." }, "style": "form", "explode": true }, { "name": "stations", "in": "query", "required": false, "description": "Semicolon-separated ICAO station identifiers. See [Available Stations](/models/version_1/availability/available-stations/) for supported IDs. Can be used instead of `coordinates`. When using station IDs, the forecast uses station-specific bias correction trained on METAR observations.", "schema": { "type": "string", "minLength": 1, "examples": [ "KJFK;PANC" ], "description": "Semicolon-separated ICAO station identifiers. See [Available Stations](/models/version_1/availability/available-stations/) for supported IDs. Can be used instead of `coordinates`. When using station IDs, the forecast uses station-specific bias correction trained on METAR observations." }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "The initialization time for the forecast.", "schema": { "type": "string", "format": "date-time", "description": "The initialization time for the forecast." }, "style": "form", "explode": true }, { "name": "min_forecast_time", "in": "query", "required": false, "description": "Earliest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Earliest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "max_forecast_time", "in": "query", "required": false, "description": "Latest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Latest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "min_forecast_hour", "in": "query", "required": false, "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "max_forecast_hour", "in": "query", "required": false, "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "coordinates" ] }, { "required": [ "stations" ] } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Total precipitation over the 3 hours ending at `time`.", "x-unit": "mm" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" }, "station_id": { "type": [ "string", "null" ], "description": "The ICAO station identifier, if the forecast was requested by station. Null when queried by coordinates." }, "apparent_temperature": { "type": [ "number", "null" ], "description": "Apparent temperature.", "x-unit": "°C" }, "p_type": { "type": [ "string", "null" ], "description": "Precipitation type: `rain`, `freezing rain`, `ice pellets`, or `snow`." }, "total_cloud_cover": { "type": [ "number", "null" ], "description": "Total cloud cover as a fraction from 0 to 1." }, "low_cloud_cover": { "type": [ "number", "null" ], "description": "Low cloud cover as a fraction from 0 to 1." }, "cloud_base_height": { "type": [ "number", "null" ], "description": "Cloud-base height.", "x-unit": "meters" }, "cape": { "type": [ "number", "null" ], "description": "Convective available potential energy.", "x-unit": "J/kg" }, "snowfall_3h": { "type": [ "number", "null" ], "description": "Three-hour snowfall, expressed as water equivalent.", "x-unit": "mm" }, "temperature_2m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ], "description": "`p10` and `p90` are the 10th and 90th percentiles, in the corresponding field’s units; either value can be null." }, "dewpoint_2m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ], "description": "`p10` and `p90` are the 10th and 90th percentiles, in the corresponding field’s units; either value can be null." }, "wind_speed_10m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ], "description": "`p10` and `p90` are the 10th and 90th percentiles, in the corresponding field’s units; either value can be null." }, "pressure_msl_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ], "description": "`p10` and `p90` are the 10th and 90th percentiles, in the corresponding field’s units; either value can be null." }, "precipitation_distribution": { "type": [ "object", "null" ], "properties": { "mean": { "type": [ "number", "null" ] }, "gt_0p25mm": { "type": [ "number", "null" ] }, "gt_2p5mm": { "type": [ "number", "null" ] }, "gt_6mm": { "type": [ "number", "null" ] }, "gt_12p5mm": { "type": [ "number", "null" ] }, "gt_25mm": { "type": [ "number", "null" ] }, "gt_50mm": { "type": [ "number", "null" ] } }, "description": "`mean` is three-hour precipitation in mm. `gt_0p25mm`, `gt_2p5mm`, `gt_6mm`, `gt_12p5mm`, `gt_25mm`, and `gt_50mm` are probabilities from 0 to 1 of exceeding each threshold; values can be null." }, "p_type_distribution": { "type": [ "object", "null" ], "properties": { "mean": { "type": [ "integer", "null" ] }, "p_rain": { "type": [ "number", "null" ] }, "p_freezing_rain": { "type": [ "number", "null" ] }, "p_ice_pellets": { "type": [ "number", "null" ] }, "p_snow": { "type": [ "number", "null" ] } }, "description": "`p_rain`, `p_freezing_rain`, `p_ice_pellets`, and `p_snow` are probabilities from 0 to 1. `mean` is the category code: 0 rain, 1 freezing rain, 2 ice pellets, 3 snow; values can be null." } }, "required": [ "time", "latitude", "longitude", "temperature_2m", "dewpoint_2m", "precipitation", "pressure_msl", "wind_u_10m", "wind_v_10m", "wind_speed_10m", "wind_u_100m", "wind_v_100m", "wind_speed_100m", "station_id" ] } }, "description": "Forecasts, in the same order as the input coordinates or stations." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "forecast_start_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Valid time of the first returned forecast point. Null when no forecast points are returned." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." } }, "required": [ "forecasts", "forecast_zero", "forecast_start_time", "initialization_time" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/observations/asos/recent": { "get": { "operationId": "get_recent_asos_observations", "summary": "Recent ASOS Observations", "description": "Retrieve recent surface observations for an ASOS station.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/observations/asos" }, "parameters": [ { "name": "station", "in": "query", "required": false, "description": "Station identifier. Accepts a three-letter US station code, four-letter ICAO code, or USAF–WBAN ID. Examples: `DFW`, `KDFW`, `72259003927`, or `722590-03927`. See [Available Stations](/models/version_1/availability/available-stations/) for supported ICAO IDs.", "schema": { "type": "string", "examples": [ "KDFW" ], "description": "Station identifier. Accepts a three-letter US station code, four-letter ICAO code, or USAF–WBAN ID. Examples: `DFW`, `KDFW`, `72259003927`, or `722590-03927`. See [Available Stations](/models/version_1/availability/available-stations/) for supported ICAO IDs." }, "style": "form", "explode": true }, { "name": "station_id", "in": "query", "required": false, "description": "Alias for `station`. Used only when `station` is omitted or empty.", "schema": { "type": "string", "examples": [ "72259003927" ], "description": "Alias for `station`. Used only when `station` is omitted or empty." }, "style": "form", "explode": true }, { "name": "hours", "in": "query", "required": false, "description": "Number of hours before the current time to return. Values below 1 or above 168 are clamped to that range. Ignored when `since` is provided.", "schema": { "type": "integer", "default": 48, "description": "Number of hours before the current time to return. Values below 1 or above 168 are clamped to that range. Ignored when `since` is provided.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "since", "in": "query", "required": false, "description": "Return observations at or after this timestamp. This takes precedence over `hours`, but the result is still limited to the endpoint's seven-day retention window.", "schema": { "type": "string", "format": "date-time", "description": "Return observations at or after this timestamp. This takes precedence over `hours`, but the result is still limited to the endpoint's seven-day retention window." }, "style": "form", "explode": true }, { "name": "include_high_frequency", "in": "query", "required": false, "description": "Include high-frequency MADIS observations in addition to the routine reports. High-frequency temperature and dewpoint values may have lower precision.", "schema": { "type": "boolean", "default": false, "description": "Include high-frequency MADIS observations in addition to the routine reports. High-frequency temperature and dewpoint values may have lower precision." }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "station" ], "properties": { "station": { "type": "string", "minLength": 1 } } }, { "required": [ "station_id" ], "properties": { "station_id": { "type": "string", "minLength": 1 } } } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "station": { "type": "object", "properties": { "station_id": { "type": "string", "description": "The station's 11-digit USAF–WBAN identifier." }, "icao": { "type": [ "string", "null" ], "description": "The station's ICAO identifier." }, "name": { "type": [ "string", "null" ], "description": "Human-readable station name." }, "elevation_m": { "type": [ "number", "null" ], "description": "Station elevation above mean sea level.", "x-unit": "meters" } }, "required": [ "station_id", "icao", "name", "elevation_m" ], "description": "Metadata for the resolved station." }, "units": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Units for numeric weather fields." }, "observations": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "Observation time in UTC with millisecond precision." }, "latitude": { "type": [ "number", "null" ], "description": "Observation latitude, or the station latitude when the report has no coordinate.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Observation longitude, or the station longitude when the report has no coordinate.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "precipitation": { "type": "number", "description": "Reported precipitation. Missing values are returned as 0.", "x-unit": "mm" } }, "required": [ "time", "latitude", "longitude", "temperature_2m", "dewpoint_2m", "pressure_msl", "wind_u_10m", "wind_v_10m", "precipitation" ] }, "description": "Observations at or after the resolved start time, ordered oldest to newest." } }, "required": [ "station", "units", "observations" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/tropical_cyclones/{tc_id}": { "get": { "operationId": "get_tropical_cyclone_detail", "summary": "Tropical Cyclone Detail", "description": "Detailed forecast for one tropical cyclone.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/tropical-cyclones/tropical-cyclone-detail" }, "parameters": [ { "name": "tc_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Tropical cyclone ID to request. Accepts an ATCF or generated ID." }, "description": "Tropical cyclone ID to request. Accepts an ATCF or generated ID." }, { "name": "initialization_time", "in": "query", "required": false, "description": "Published initialization time to return.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" }, { "type": "string", "const": "latest" } ], "description": "Published initialization time to return." }, "style": "form", "explode": true }, { "name": "include_members", "in": "query", "required": false, "description": "Include ensemble-member paths.", "schema": { "type": "boolean", "default": false, "description": "Include ensemble-member paths." }, "style": "form", "explode": true }, { "name": "include_cones", "in": "query", "required": false, "description": "Include the ensemble-weighted cone when available.", "schema": { "type": "boolean", "default": false, "description": "Include the ensemble-weighted cone when available." }, "style": "form", "explode": true }, { "name": "format", "in": "query", "required": false, "description": "Response representation.", "schema": { "type": "string", "enum": [ "json", "geojson", "deck" ], "default": "json", "description": "Response representation." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response in the requested format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string", "description": "Operational ATCF ID, or the generated ID for an unmatched track." }, "storm_name": { "type": [ "string", "null" ], "description": "Operational storm name, when available." }, "basins": { "type": "array", "items": { "type": "string" }, "description": "Basins occupied by the cyclone, in first-seen order." }, "genesis": { "type": [ "object", "null" ], "properties": { "latitude": { "type": [ "number", "null" ], "description": "Genesis latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Genesis longitude, rounded to 0.0001°.", "x-unit": "degrees" } }, "required": [ "latitude", "longitude" ], "description": "Earliest published tropical or subtropical position." }, "start_time": { "type": "string", "format": "date-time", "description": "Earliest track time for the selected initialization time." }, "end_time": { "type": "string", "format": "date-time", "description": "Latest track time for the selected initialization time." }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Maximum sustained wind over the forecast track, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Minimum mean sea-level pressure, rounded to 0.1 hPa.", "x-unit": "hPa" }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "landfalls": { "type": "array", "items": { "type": "object", "properties": { "valid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Interpolated crossing time." }, "latitude": { "type": [ "number", "null" ], "description": "Crossing latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Crossing longitude, rounded to 0.0001°.", "x-unit": "degrees" }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Member maximum sustained wind interpolated to landfall, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Interpolated member pressure, rounded to 0.1 hPa.", "x-unit": "hPa" }, "storm_type": { "type": [ "string", "null" ], "description": "The cyclone’s meteorological classification." }, "ensemble_member": { "type": "integer", "description": "Member that produced the crossing." } }, "required": [ "valid_at", "latitude", "longitude", "max_wind_kt", "min_mslp_hpa", "storm_type", "ensemble_member" ] }, "description": "Water-to-land crossings from individual member paths. Crossings within 20 miles on the same connected landmass are consolidated. Landfall locations use NOAA GSHHG 2.3.7's high-resolution shoreline polygons." }, "mean_path": { "type": "array", "items": { "type": "object", "properties": { "valid_at": { "type": "string", "format": "date-time", "description": "Point valid time." }, "forecast_hour": { "type": "integer", "description": "Forecast hour from `forecast_zero`.", "x-unit": "hours" }, "latitude": { "type": [ "number", "null" ], "description": "Mean latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Mean longitude, rounded to 0.0001°.", "x-unit": "degrees" }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Ensemble-mean maximum sustained wind, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Mean cyclone-center pressure, rounded to 0.1 hPa.", "x-unit": "hPa" }, "storm_type": { "type": [ "string", "null" ], "description": "The cyclone’s meteorological classification." }, "contributing_members_count": { "type": "integer", "description": "Members contributing to this mean point." } }, "required": [ "valid_at", "forecast_hour", "latitude", "longitude", "max_wind_kt", "min_mslp_hpa", "storm_type" ] }, "description": "Ensemble-mean path for a matched storm; empty for an unmatched track." }, "matched_members": { "type": "integer", "description": "Member tracks represented by this cyclone." }, "ens_size": { "type": "integer", "description": "Full ensemble size." }, "members_path": { "type": "array", "items": { "type": "object", "properties": { "member": { "type": "integer", "description": "Ensemble member number." }, "path": { "type": "array", "items": { "type": "object", "properties": { "valid_at": { "type": "string", "format": "date-time" }, "forecast_hour": { "type": "integer" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "max_wind_kt": { "type": [ "number", "null" ] }, "min_mslp_hpa": { "type": [ "number", "null" ] }, "storm_type": { "type": [ "string", "null" ] }, "contributing_members_count": { "type": "integer" } }, "required": [ "valid_at", "forecast_hour", "latitude", "longitude", "max_wind_kt", "min_mslp_hpa", "storm_type" ] }, "description": "Path points with the same fields as `mean_path`, except contributor count. Values describe the individual member." } }, "required": [ "member", "path" ] }, "description": "Member paths.", "x-present-when": "`include_members=true`" }, "cones": { "type": "array", "items": { "type": "object", "properties": { "members_total": { "type": "integer", "description": "Full ensemble size used as the cone-density denominator." }, "max_forecast_hour": { "type": "integer", "description": "Last forecast hour represented by the cone.", "x-unit": "hours" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "Cone shape, with coordinates rounded to 0.0001°." } }, "required": [ "members_total", "max_forecast_hour", "geometry" ] }, "description": "Ensemble-weighted cone.", "x-present-when": "`include_cones=true` and a cone is available" } }, "required": [ "tropical_cyclone_id", "storm_name", "basins", "genesis", "start_time", "end_time", "max_wind_kt", "min_mslp_hpa", "initialization_time", "forecast_zero", "landfalls", "mean_path", "matched_members", "ens_size" ] } }, "application/geo+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection" }, "initialization_time": { "type": "string", "format": "date-time" }, "forecast_zero": { "type": "string", "format": "date-time" }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "properties": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string" }, "storm_name": { "type": [ "string", "null" ] }, "basins": { "type": "array", "items": { "type": "string" } }, "feature_type": { "type": "string" }, "valid_at": { "type": "string", "format": "date-time" }, "forecast_hour": { "type": "integer" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "max_wind_kt": { "type": [ "number", "null" ] }, "min_mslp_hpa": { "type": [ "number", "null" ] }, "storm_type": { "type": [ "string", "null" ] }, "contributing_members_count": { "type": "integer" }, "members_total": { "type": "integer" }, "max_forecast_hour": { "type": "integer" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "member": { "type": "integer" }, "path_type": { "type": "string" }, "ensemble_member": { "type": "integer" } }, "required": [ "tropical_cyclone_id", "storm_name", "basins", "feature_type" ] } }, "required": [ "type", "geometry", "properties" ] } } }, "required": [ "type", "initialization_time", "forecast_zero", "features" ] } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/tropical_cyclones/{tc_id}/initialization_times": { "get": { "operationId": "get_tropical_cyclone_init_times", "summary": "Initialization Times for Tropical Cyclone", "description": "List initialization times available for a tropical cyclone.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/tropical-cyclones/tropical-cyclone-init-times" }, "parameters": [ { "name": "tc_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Tropical cyclone ID to request. Accepts an ATCF or generated ID." }, "description": "Tropical cyclone ID to request. Accepts an ATCF or generated ID." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string", "description": "Resolved operational ATCF ID, or the generated ID for an unmatched track." }, "available": { "type": "array", "items": { "type": "string", "format": "date-time" }, "description": "Initialization times for which the tropical cyclone is available, sorted from earliest to latest." }, "latest": { "type": "string", "format": "date-time", "description": "Latest available initialization time." } }, "required": [ "tropical_cyclone_id", "available", "latest" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/tropical_cyclones": { "get": { "operationId": "get_tropical_cyclones", "summary": "Tropical Cyclones", "description": "Forecasts for all active tropical cyclones.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/tropical-cyclones/tropical-cyclones" }, "parameters": [ { "name": "initialization_time", "in": "query", "required": false, "description": "Published initialization time to return.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" }, { "type": "string", "const": "latest" } ], "description": "Published initialization time to return." }, "style": "form", "explode": true }, { "name": "basin", "in": "query", "required": false, "description": "Return cyclones in this basin for the selected initialization time.", "schema": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ], "description": "Return cyclones in this basin for the selected initialization time." }, "style": "form", "explode": true }, { "name": "include_unofficial_ids", "in": "query", "required": false, "description": "Also include unmatched ensemble member tracks.", "schema": { "type": "boolean", "default": false, "description": "Also include unmatched ensemble member tracks." }, "style": "form", "explode": true }, { "name": "include_details", "in": "query", "required": false, "description": "Include paths, member landfalls, and cones. A matched storm's path is the ensemble mean; an unmatched track's path is its single-member track.", "schema": { "type": "boolean", "default": false, "description": "Include paths, member landfalls, and cones. A matched storm's path is the ensemble mean; an unmatched track's path is its single-member track." }, "style": "form", "explode": true }, { "name": "format", "in": "query", "required": false, "description": "Return JSON or map-ready GeoJSON.", "schema": { "type": "string", "enum": [ "json", "geojson" ], "default": "json", "description": "Return JSON or map-ready GeoJSON." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response in the requested format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "initialization_time": { "type": "string", "format": "date-time", "description": "Published initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "tropical_cyclones": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string", "description": "Operational ATCF ID, or a generated ID when unofficial IDs were requested." }, "storm_name": { "type": [ "string", "null" ], "description": "Operational storm name, when available." }, "basins": { "type": "array", "items": { "type": "string" }, "description": "Basins occupied by the cyclone, in first-seen order." }, "genesis": { "type": [ "object", "null" ], "properties": { "latitude": { "type": [ "number", "null" ], "description": "Genesis latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Genesis longitude, rounded to 0.0001°.", "x-unit": "degrees" } }, "required": [ "latitude", "longitude" ], "description": "Earliest published tropical or subtropical position. Always included." }, "start_time": { "type": "string", "format": "date-time", "description": "Earliest track time for the selected initialization time." }, "end_time": { "type": "string", "format": "date-time", "description": "Latest track time for the selected initialization time." }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Maximum sustained wind over the forecast track, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Minimum mean sea-level pressure, rounded to 0.1 hPa.", "x-unit": "hPa" }, "landfalls": { "type": "array", "items": { "type": "object", "properties": { "valid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Interpolated crossing time." }, "latitude": { "type": [ "number", "null" ], "description": "Crossing latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Crossing longitude, rounded to 0.0001°.", "x-unit": "degrees" }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Member maximum sustained wind interpolated to landfall, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Interpolated member pressure, rounded to 0.1 hPa.", "x-unit": "hPa" }, "storm_type": { "type": [ "string", "null" ], "description": "The cyclone’s meteorological classification." }, "ensemble_member": { "type": "integer", "description": "Member that produced the crossing." } }, "required": [ "valid_at", "latitude", "longitude", "max_wind_kt", "min_mslp_hpa", "storm_type", "ensemble_member" ] }, "description": "Individual member water-to-land crossings. Crossings within 20 miles on the same connected landmass are consolidated. Landfall locations use NOAA GSHHG 2.3.7's high-resolution shoreline polygons.", "x-present-when": "`include_details=true`" }, "path": { "type": "array", "items": { "type": "object", "properties": { "valid_at": { "type": "string", "format": "date-time", "description": "Point valid time." }, "forecast_hour": { "type": "integer", "description": "Forecast hour from `forecast_zero`.", "x-unit": "hours" }, "latitude": { "type": [ "number", "null" ], "description": "Path latitude, rounded to 0.0001°.", "x-unit": "degrees" }, "longitude": { "type": [ "number", "null" ], "description": "Path longitude, rounded to 0.0001°.", "x-unit": "degrees" }, "max_wind_kt": { "type": [ "number", "null" ], "description": "Maximum sustained wind, rounded to 0.1 kt.", "x-unit": "kt" }, "min_mslp_hpa": { "type": [ "number", "null" ], "description": "Cyclone-center pressure at this path point, rounded to 0.1 hPa.", "x-unit": "hPa" }, "storm_type": { "type": [ "string", "null" ], "description": "The cyclone’s meteorological classification." }, "contributing_members_count": { "type": "integer", "description": "Members contributing to this path point; 1 for an unmatched track." } }, "required": [ "valid_at", "forecast_hour", "latitude", "longitude", "max_wind_kt", "min_mslp_hpa", "storm_type" ] }, "description": "Ensemble-mean path for a matched storm, or the single-member track for an unmatched track.", "x-present-when": "`include_details=true`" }, "cone": { "type": [ "object", "null" ], "properties": { "members_total": { "type": "integer", "description": "Full ensemble size used as the cone-density denominator." }, "max_forecast_hour": { "type": "integer", "description": "Last forecast hour represented by the cone.", "x-unit": "hours" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ], "description": "Cone shape, with coordinates rounded to 0.0001°." } }, "required": [ "members_total", "max_forecast_hour", "geometry" ], "description": "Ensemble-weighted uncertainty cone.", "x-present-when": "`include_details=true` and a cone is available" } }, "required": [ "tropical_cyclone_id", "storm_name", "basins", "genesis", "start_time", "end_time", "max_wind_kt", "min_mslp_hpa" ], "description": "Forecast summary for one cyclone." }, "description": "Keyed by tropical cyclone ID." }, "total": { "type": "integer", "description": "Total cyclones returned." } }, "required": [ "initialization_time", "forecast_zero", "tropical_cyclones", "total" ] } }, "application/geo+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection" }, "initialization_time": { "type": "string", "format": "date-time" }, "forecast_zero": { "type": "string", "format": "date-time" }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "properties": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string" }, "storm_name": { "type": [ "string", "null" ] }, "basins": { "type": "array", "items": { "type": "string" } }, "feature_type": { "type": "string" }, "valid_at": { "type": "string", "format": "date-time" }, "forecast_hour": { "type": "integer" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "max_wind_kt": { "type": [ "number", "null" ] }, "min_mslp_hpa": { "type": [ "number", "null" ] }, "storm_type": { "type": [ "string", "null" ] }, "contributing_members_count": { "type": "integer" }, "members_total": { "type": "integer" }, "max_forecast_hour": { "type": "integer" }, "geometry": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "Point", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "LineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiLineString", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "Polygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "required": [ "type", "coordinates" ] }, { "type": "object", "properties": { "type": { "const": "MultiPolygon", "type": "string" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } } }, "required": [ "type", "coordinates" ] } ] }, "member": { "type": "integer" }, "path_type": { "type": "string" }, "ensemble_member": { "type": "integer" } }, "required": [ "tropical_cyclone_id", "storm_name", "basins", "feature_type" ] } }, "required": [ "type", "geometry", "properties" ] } } }, "required": [ "type", "initialization_time", "forecast_zero", "features" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/events/tropical_cyclones/index": { "get": { "operationId": "get_tropical_cyclones_index", "summary": "Index Tropical Cyclones", "description": "Browse the tropical cyclone catalog.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/events/tropical-cyclones/tropical-cyclones-index" }, "parameters": [ { "name": "basin", "in": "query", "required": false, "description": "Return cyclones that occupied this basin at any published initialization time.", "schema": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ], "description": "Return cyclones that occupied this basin at any published initialization time." }, "style": "form", "explode": true }, { "name": "include_unofficial_ids", "in": "query", "required": false, "description": "Also include unmatched ensemble member tracks.", "schema": { "type": "boolean", "default": false, "description": "Also include unmatched ensemble member tracks." }, "style": "form", "explode": true }, { "name": "min_time", "in": "query", "required": false, "description": "Return cyclones whose published lifetime ends at or after this time. May be used independently or with `max_time`.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" } ], "description": "Return cyclones whose published lifetime ends at or after this time. May be used independently or with `max_time`." }, "style": "form", "explode": true }, { "name": "max_time", "in": "query", "required": false, "description": "Return cyclones whose published lifetime begins at or before this time. May be used independently or with `min_time`.", "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{10}$" } ], "description": "Return cyclones whose published lifetime begins at or before this time. May be used independently or with `min_time`." }, "style": "form", "explode": true }, { "name": "page", "in": "query", "required": false, "description": "Zero-indexed page number.", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero-indexed page number." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 64, "description": "Number of results per page." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tropical_cyclones": { "type": "object", "additionalProperties": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string", "description": "Operational ATCF ID, or a generated ID when unofficial IDs were requested." }, "storm_name": { "type": [ "string", "null" ], "description": "Operational storm name, when available." }, "basins": { "type": "array", "items": { "type": "string" }, "description": "Basins occupied by the cyclone, in first-seen order." }, "start_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest track time across all initialization times." }, "end_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest track time across all initialization times." } }, "required": [ "tropical_cyclone_id", "storm_name", "basins", "start_time", "end_time" ], "description": "Metadata for one cyclone." }, "description": "Keyed by tropical cyclone ID." }, "total": { "type": "integer", "description": "Total number of matching cyclones." }, "page": { "type": "integer", "description": "Current page number." }, "page_size": { "type": "integer", "description": "Number of results per page." } }, "required": [ "tropical_cyclones", "total", "page", "page_size" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/context": { "get": { "operationId": "get_weather_context", "summary": "Weather Context", "description": "Fetch forecasts and optional context for weather agents in one request.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/context/weather-context" }, "parameters": [ { "name": "coordinates", "in": "query", "required": false, "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order. Use this, `stations`, or both.", "schema": { "type": "string", "minLength": 1, "examples": [ "37.77,-122.42" ], "description": "Latitude,longitude pairs separated by semicolons, for example `37,-121;40.3,-100`. Results preserve the input order. Use this, `stations`, or both." }, "style": "form", "explode": true }, { "name": "stations", "in": "query", "required": false, "description": "Comma- or semicolon-separated ICAO station identifiers. Results for `coordinates` come first. See [Available Stations](/models/version_1/availability/available-stations/) for supported IDs.", "schema": { "type": "string", "minLength": 1, "examples": [ "KJFK;PANC" ], "description": "Comma- or semicolon-separated ICAO station identifiers. Results for `coordinates` come first. See [Available Stations](/models/version_1/availability/available-stations/) for supported IDs." }, "style": "form", "explode": true }, { "name": "include_conditions", "in": "query", "required": false, "description": "Add hourly, daily, and day/night summaries in `conditions`.", "schema": { "type": "boolean", "default": false, "description": "Add hourly, daily, and day/night summaries in `conditions`." }, "style": "form", "explode": true }, { "name": "include_observations", "in": "query", "required": false, "description": "Add recent routine ASOS reports in `observations`. Coordinates use the nearest ASOS station.", "schema": { "type": "boolean", "default": false, "description": "Add recent routine ASOS reports in `observations`. Coordinates use the nearest ASOS station." }, "style": "form", "explode": true }, { "name": "include_distribution", "in": "query", "required": false, "description": "Add p10/p90 ranges for supported scalar fields, precipitation probabilities, and precipitation-type probabilities to each forecast point.", "schema": { "type": "boolean", "default": false, "description": "Add p10/p90 ranges for supported scalar fields, precipitation probabilities, and precipitation-type probabilities to each forecast point." }, "style": "form", "explode": true }, { "name": "include_climatology", "in": "query", "required": false, "description": "Add hourly ERA5 normals from the first through last returned forecast time in `climatologies`. This can include hours between forecast points.", "schema": { "type": "boolean", "default": false, "description": "Add hourly ERA5 normals from the first through last returned forecast time in `climatologies`. This can include hours between forecast points." }, "style": "form", "explode": true }, { "name": "include_climatology_summary", "in": "query", "required": false, "description": "Add one ERA5 daily normal per local date covered by each forecast in `climatology_summaries`.", "schema": { "type": "boolean", "default": false, "description": "Add one ERA5 daily normal per local date covered by each forecast in `climatology_summaries`." }, "style": "form", "explode": true }, { "name": "initialization_time", "in": "query", "required": false, "description": "Select an exact MetaMesh run for station forecasts.", "schema": { "type": "string", "format": "date-time", "description": "Select an exact MetaMesh run for station forecasts." }, "style": "form", "explode": true }, { "name": "min_forecast_hour", "in": "query", "required": false, "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "minimum": 0, "maximum": 360, "default": 0, "description": "Earliest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "max_forecast_hour", "in": "query", "required": false, "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "schema": { "type": "integer", "minimum": 0, "maximum": 360, "default": 360, "description": "Latest forecast hour to include in the response, counted from `forecast_zero`.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "min_forecast_time", "in": "query", "required": false, "description": "Earliest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Earliest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "max_forecast_time", "in": "query", "required": false, "description": "Latest valid time to include in the response.", "schema": { "type": "string", "format": "date-time", "description": "Latest valid time to include in the response." }, "style": "form", "explode": true }, { "name": "observation_hours", "in": "query", "required": false, "description": "Number of hours before the current time to return. Used only when `include_observations` is true.", "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 48, "description": "Number of hours before the current time to return. Used only when `include_observations` is true.", "x-unit": "hours" }, "style": "form", "explode": true }, { "name": "climatology_normal", "in": "query", "required": false, "description": "Normal period to use. Used when `include_climatology` or `include_climatology_summary` is true.", "schema": { "type": "string", "enum": [ "1991-2020", "2011-2020", "2016-2025" ], "default": "1991-2020", "description": "Normal period to use. Used when `include_climatology` or `include_climatology_summary` is true." }, "style": "form", "explode": true } ], "x-query-constraint": { "anyOf": [ { "required": [ "coordinates" ] }, { "required": [ "stations" ] } ] }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "temperature_2m": { "type": [ "number", "null" ] }, "dewpoint_2m": { "type": [ "number", "null" ] }, "precipitation": { "type": [ "number", "null" ] }, "pressure_msl": { "type": [ "number", "null" ] }, "wind_u_10m": { "type": [ "number", "null" ] }, "wind_v_10m": { "type": [ "number", "null" ] }, "wind_speed_10m": { "type": [ "number", "null" ] }, "wind_u_100m": { "type": [ "number", "null" ] }, "wind_v_100m": { "type": [ "number", "null" ] }, "wind_speed_100m": { "type": [ "number", "null" ] }, "station_id": { "type": [ "string", "null" ] }, "apparent_temperature": { "type": [ "number", "null" ] }, "p_type": { "type": [ "string", "null" ] }, "total_cloud_cover": { "type": [ "number", "null" ] }, "low_cloud_cover": { "type": [ "number", "null" ] }, "cloud_base_height": { "type": [ "number", "null" ] }, "cape": { "type": [ "number", "null" ] }, "snowfall_3h": { "type": [ "number", "null" ] }, "temperature_2m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ] }, "dewpoint_2m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ] }, "wind_speed_10m_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ] }, "pressure_msl_distribution": { "type": [ "object", "null" ], "properties": { "p10": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] } }, "required": [ "p10", "p90" ] }, "precipitation_distribution": { "type": [ "object", "null" ], "properties": { "mean": { "type": [ "number", "null" ] }, "gt_0p25mm": { "type": [ "number", "null" ] }, "gt_2p5mm": { "type": [ "number", "null" ] }, "gt_6mm": { "type": [ "number", "null" ] }, "gt_12p5mm": { "type": [ "number", "null" ] }, "gt_25mm": { "type": [ "number", "null" ] }, "gt_50mm": { "type": [ "number", "null" ] } } }, "p_type_distribution": { "type": [ "object", "null" ], "properties": { "mean": { "type": [ "integer", "null" ] }, "p_rain": { "type": [ "number", "null" ] }, "p_freezing_rain": { "type": [ "number", "null" ] }, "p_ice_pellets": { "type": [ "number", "null" ] }, "p_snow": { "type": [ "number", "null" ] } } } }, "required": [ "time", "latitude", "longitude", "temperature_2m", "dewpoint_2m", "precipitation", "pressure_msl", "wind_u_10m", "wind_v_10m", "wind_speed_10m", "wind_u_100m", "wind_v_100m", "wind_speed_100m", "station_id" ] } }, "description": "One MetaMesh series per location. See [Point Forecast](/weather/version_1/point/point-forecast/)." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "forecast_start_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Valid time of the first returned forecast point. Null when no forecast points are returned." }, "initialization_time": { "type": "string", "format": "date-time", "description": "MetaMesh initialization time." }, "conditions": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "timezone": { "type": "string" }, "hourly": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri" }, "sky_state_icon_url": { "type": "string", "format": "uri" }, "sky_state_condition": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "type": "string" } }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "period": { "type": "string" } }, "required": [ "icon_url", "sky_state_icon_url", "sky_state_condition", "conditions", "start_time", "end_time", "text" ] } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri" }, "sky_state_icon_url": { "type": "string", "format": "uri" }, "sky_state_condition": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "type": "string" } }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "period": { "type": "string" } }, "required": [ "icon_url", "sky_state_icon_url", "sky_state_condition", "conditions", "start_time", "end_time", "text" ] } }, "day_night": { "type": "array", "items": { "type": "object", "properties": { "icon_url": { "type": "string", "format": "uri" }, "sky_state_icon_url": { "type": "string", "format": "uri" }, "sky_state_condition": { "type": [ "string", "null" ] }, "conditions": { "type": "array", "items": { "type": "string" } }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "text": { "type": "string" }, "period": { "type": "string" } }, "required": [ "icon_url", "sky_state_icon_url", "sky_state_condition", "conditions", "start_time", "end_time", "text" ] } } }, "required": [ "latitude", "longitude", "timezone", "hourly", "daily", "day_night" ] }, "description": "One summary set per location, including `sky_state_icon_url` and `sky_state_condition` in every block whenever `include_conditions=true`. See [Conditions](/models/version_1/outputs/conditions/).", "x-present-when": "`include_conditions=true`" }, "observations": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "station_id": { "type": "string" }, "temperature_2m": { "type": [ "number", "null" ] }, "dewpoint_2m": { "type": [ "number", "null" ] }, "pressure_msl": { "type": [ "number", "null" ] }, "wind_u_10m": { "type": [ "number", "null" ] }, "wind_v_10m": { "type": [ "number", "null" ] }, "precipitation": { "type": "number" } }, "required": [ "time", "latitude", "longitude", "station_id", "temperature_2m", "dewpoint_2m", "pressure_msl", "wind_u_10m", "wind_v_10m", "precipitation" ] } }, "description": "One chronological ASOS series per location. See [ASOS Observations](/weather/version_1/observations/asos/).", "x-present-when": "`include_observations=true`" }, "climatology_normal": { "type": "string", "description": "The normal period used.", "x-present-when": "`include_climatology` or `include_climatology_summary` is true" }, "climatologies": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "temperature_2m": { "type": [ "number", "null" ] }, "dewpoint_2m": { "type": [ "number", "null" ] }, "precipitation": { "type": [ "number", "null" ] }, "pressure_msl": { "type": "null" }, "wind_u_10m": { "type": [ "number", "null" ] }, "wind_v_10m": { "type": [ "number", "null" ] }, "wind_speed_10m": { "type": [ "number", "null" ] }, "wind_u_100m": { "type": [ "number", "null" ] }, "wind_v_100m": { "type": [ "number", "null" ] }, "wind_speed_100m": { "type": [ "number", "null" ] } }, "required": [ "time", "latitude", "longitude", "temperature_2m", "dewpoint_2m", "precipitation", "pressure_msl", "wind_u_10m", "wind_v_10m", "wind_speed_10m", "wind_u_100m", "wind_v_100m", "wind_speed_100m" ] } }, "description": "One hourly normal series per forecast location, covering every hour from its first through last forecast time. Empty forecasts produce empty arrays. See [Climatology](/weather/version_1/climatology/climatology/).", "x-present-when": "`include_climatology=true`" }, "climatology_summaries": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "standard_utc_offset_minutes": { "type": "integer" }, "temperature_2m_min": { "type": [ "number", "null" ] }, "temperature_2m_max": { "type": [ "number", "null" ] }, "dewpoint_2m_min": { "type": [ "number", "null" ] }, "dewpoint_2m_max": { "type": [ "number", "null" ] }, "precipitation": { "type": [ "number", "null" ] }, "avg_daily_precipitation": { "type": [ "number", "null" ] }, "wind_speed_10m_mean": { "type": [ "number", "null" ] }, "wind_speed_10m_max": { "type": [ "number", "null" ] } }, "required": [ "start_date", "end_date", "latitude", "longitude", "standard_utc_offset_minutes", "temperature_2m_min", "temperature_2m_max", "dewpoint_2m_min", "dewpoint_2m_max", "precipitation", "avg_daily_precipitation", "wind_speed_10m_mean", "wind_speed_10m_max" ] } }, "description": "One daily series per location, from its first through last forecast date. Dates use the location's fixed standard UTC offset, so a UTC forecast time may belong to the previous local date. Empty forecasts produce empty arrays. See [Climatology Summary](/weather/version_1/climatology/climatology-summary/).", "x-present-when": "`include_climatology_summary=true`" }, "units": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Units for numeric weather fields. Always present." } }, "required": [ "forecasts", "forecast_zero", "forecast_start_time", "initialization_time", "units" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/weather/v1/custom-calculations/validate": { "post": { "operationId": "validate_calculation", "summary": "Validate Calculation", "description": "Check a custom calculation expression before requesting calculated data.", "tags": [ "Weather" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/weather/version_1/custom-calculations/validate-calculation" }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "calculation": { "type": "string", "minLength": 1, "description": "Custom calculation expression to validate. See [About Custom Calculations](/weather/version_1/custom-calculations/about/) for syntax and examples." } }, "required": [ "calculation" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Whether the calculation follows the language rules." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Error category, such as `INVALID_CALCULATION`, `INVALID_LEVEL_SELECTION`, or `INVALID_TIME_WINDOW`." }, "message": { "type": "string", "description": "Description of the problem, including its location in the calculation when available." }, "forecast_hour_errors": { "type": "array", "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "forecast_hour", "code", "message" ] } } }, "required": [ "code", "message" ] }, "description": "Validation errors. Empty when `valid` is `true`." } }, "required": [ "valid", "errors" ] } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "406": { "description": "Request failed." }, "429": { "description": "Rate limit exceeded." }, "500": { "description": "Server error." }, "502": { "description": "Upstream service error." }, "503": { "description": "Data or service unavailable." } } } }, "/webhooks/v1/{id}/subscriptions": { "patch": { "operationId": "add_webhook_subscription", "summary": "Add Subscription", "description": "Add a new subscription to an existing webhook.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/subscriptions/add-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "subscription_type": { "const": "initialization_time.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "forecast_hour.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "events.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ], "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "degree_days.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "tropical_cyclones.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] } ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "put": { "operationId": "add_webhook_subscription_put", "x-alias-of": "add_webhook_subscription", "summary": "Add Subscription", "description": "Add a new subscription to an existing webhook.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/subscriptions/add-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "subscription_type": { "const": "initialization_time.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "forecast_hour.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "events.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ], "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "degree_days.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] }, { "type": "object", "properties": { "subscription_type": { "const": "tropical_cyclones.available", "description": "The subscription type to add." }, "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility. Invalid configurations return `422`." } }, "required": [ "subscription_type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ] } ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } } }, "/webhooks/v1": { "post": { "operationId": "create_webhook", "summary": "Create Webhook", "description": "Register a new webhook endpoint with optional subscriptions.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/create-webhook" }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The HTTPS URL to deliver payloads to. Must be publicly reachable." }, "name": { "type": [ "string", "null" ], "description": "Webhook name." }, "note": { "type": [ "string", "null" ], "description": "Free-text description returned with every delivery. Useful for providing context to LLMs or downstream automation." }, "subscriptions": { "type": [ "object", "null" ], "properties": { "initialization_time.available": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ], "description": "Subscription type key. For example: `initialization_time.available` or `forecast_hour.available`. See [Forecast Subscriptions](/webhooks/version_1/forecasts/initialization-time-available/)." }, "forecast_hour.available": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ], "description": "Subscription type key. For example: `initialization_time.available` or `forecast_hour.available`. See [Forecast Subscriptions](/webhooks/version_1/forecasts/initialization-time-available/)." }, "events.available": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ], "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ], "description": "Subscription type key. For example: `initialization_time.available` or `forecast_hour.available`. See [Forecast Subscriptions](/webhooks/version_1/forecasts/initialization-time-available/)." }, "degree_days.available": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ], "description": "Subscription type key. For example: `initialization_time.available` or `forecast_hour.available`. See [Forecast Subscriptions](/webhooks/version_1/forecasts/initialization-time-available/)." }, "tropical_cyclones.available": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false, "description": "Filters for this subscription type. If omitted, all notifications for the subscription type are delivered." }, "response_options": { "anyOf": [ { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "null" } ], "description": "Attach one compatible forecast response inside `data.response`. See [Attaching Forecast Responses](/webhooks/version_1/overview/#attaching-forecast-responses) for configuration and compatibility." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "response_options": { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] } }, "required": [ "type", "options" ] } }, "required": [ "response_options" ] }, "then": { "required": [ "filters" ], "properties": { "filters": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "required": [ "model" ] } } } } ], "description": "Subscription type key. For example: `initialization_time.available` or `forecast_hour.available`. See [Forecast Subscriptions](/webhooks/version_1/forecasts/initialization-time-available/)." } }, "additionalProperties": false, "description": "Subscriptions to create, keyed by subscription type. If omitted, the webhook receives no deliveries." }, "active": { "type": "boolean", "default": true, "description": "Whether the webhook is enabled." } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] }, { "type": "object", "properties": { "signing_secret": { "type": "string", "writeOnly": false, "description": "Secret used to verify delivery signatures. Returned only at creation. Store it securely." } }, "required": [ "signing_secret" ] } ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "get": { "operationId": "list_webhooks", "summary": "List Webhooks", "description": "Retrieve a paginated list of your webhooks.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/list-webhooks" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number." }, "style": "form", "explode": true }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of results per page." }, "style": "form", "explode": true }, { "name": "active", "in": "query", "required": false, "description": "Filter by active state. Omit to return all states.", "schema": { "type": "boolean", "description": "Filter by active state. Omit to return all states." }, "style": "form", "explode": true }, { "name": "subscription_type", "in": "query", "required": false, "description": "Filter to webhooks with a specific subscription type.", "schema": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "Filter to webhooks with a specific subscription type." }, "style": "form", "explode": true }, { "name": "url", "in": "query", "required": false, "description": "Partial URL match. Returns webhooks whose URL contains this string.", "schema": { "type": "string", "description": "Partial URL match. Returns webhooks whose URL contains this string." }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Free-text label. Returns null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Summary of subscriptions." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] }, "description": "Webhook summary objects." }, "page": { "type": "integer", "minimum": 1, "description": "Current page number." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of results requested for this page." }, "total": { "type": "integer", "minimum": 0, "description": "Total webhooks across all pages." } }, "required": [ "webhooks", "page", "page_size", "total" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } } }, "/webhooks/v1/{id}": { "delete": { "operationId": "delete_webhook", "summary": "Delete Webhook", "description": "Permanently delete a webhook and all its subscriptions.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/delete-webhook" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "responses": { "204": { "description": "Successful request; no response body." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "get": { "operationId": "get_webhook", "summary": "Get Webhook", "description": "Retrieve full details of a single webhook, including active subscriptions.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/get-webhook" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "patch": { "operationId": "update_webhook", "summary": "Update Webhook", "description": "Update webhook properties such as URL, name, note, or active state.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/update-webhook" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The HTTPS URL to deliver payloads to. Must be publicly reachable." }, "name": { "type": [ "string", "null" ], "description": "Webhook name." }, "note": { "type": [ "string", "null" ], "description": "Free-text description returned with every delivery. Useful for providing context to LLMs or downstream automation." }, "active": { "type": "boolean", "description": "Whether the webhook is enabled." } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "put": { "operationId": "update_webhook_put", "x-alias-of": "update_webhook", "summary": "Update Webhook", "description": "Update webhook properties such as URL, name, note, or active state.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/manage/update-webhook" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The HTTPS URL to deliver payloads to. Must be publicly reachable." }, "name": { "type": [ "string", "null" ], "description": "Webhook name." }, "note": { "type": [ "string", "null" ], "description": "Free-text description returned with every delivery. Useful for providing context to LLMs or downstream automation." }, "active": { "type": "boolean", "description": "Whether the webhook is enabled." } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } } }, "/webhooks/v1/{id}/subscriptions/{subscription_id}": { "delete": { "operationId": "delete_webhook_subscription", "summary": "Delete Subscription", "description": "Remove a single subscription from a webhook.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/subscriptions/delete-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "description": "Unique subscription identifier." } ], "responses": { "204": { "description": "Successful request; no response body." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "patch": { "operationId": "update_webhook_subscription", "summary": "Update Subscription", "description": "Partially update a single subscription.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/subscriptions/update-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "description": "Unique subscription identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Complete replacement filter object. Omit to preserve filters. Send an empty object to clear all filters. Omitting one filter from this object removes that filter while retaining the supplied filters." }, "response_options": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Complete replacement response configuration. Omit to preserve it; send another compatible object to replace it; send `null` to remove response enrichment. Invalid configurations return `422`." } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } }, "put": { "operationId": "update_webhook_subscription_put", "x-alias-of": "update_webhook_subscription", "summary": "Update Subscription", "description": "Partially update a single subscription.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/subscriptions/update-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "description": "Unique subscription identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Free-text label included in every outgoing payload for this subscription. Useful for providing context to LLMs or downstream automation." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Complete replacement filter object. Omit to preserve filters. Send an empty object to clear all filters. Omitting one filter from this object removes that filter while retaining the supplied filters." }, "response_options": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Complete replacement response configuration. Omit to preserve it; send another compatible object to replace it; send `null` to remove response enrichment. Invalid configurations return `422`." } } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "name": { "type": [ "string", "null" ], "description": "Webhook name. Null when not set." }, "note": { "type": [ "string", "null" ], "description": "Free-text description. Returns null when not set." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The registered payload URL." }, "active": { "type": "boolean", "description": "Whether this webhook is enabled for automatic deliveries." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "subscription_type": { "type": "string", "enum": [ "initialization_time.available", "forecast_hour.available", "events.available", "degree_days.available", "tropical_cyclones.available" ], "description": "The subscription type." }, "note": { "type": [ "string", "null" ], "description": "Subscription note. Null when not set." }, "filters": { "anyOf": [ { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6", "wm6-3km", "wm-6-3km", "wm6-3km-conus", "wm-6-3km-conus" ] }, "minItems": 1 } ] }, "forecast_hour": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "initialization_time_hours": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]?[0-9]|2[0-3]):[0-5][0-9]$" }, "minItems": 1 } ] }, "min_initialization_time": { "type": "string", "format": "date-time" }, "max_initialization_time": { "type": "string", "format": "date-time" }, "min_valid_at": { "type": "string", "format": "date-time" }, "max_valid_at": { "type": "string", "format": "date-time" }, "model": { "anyOf": [ { "type": "string", "enum": [ "wm6", "wm-6" ] }, { "type": "array", "items": { "type": "string", "enum": [ "wm6", "wm-6" ] }, "minItems": 1 } ] }, "event_type": { "anyOf": [ { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ] }, { "type": "array", "items": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "minItems": 1 }, { "type": "array", "items": { "const": "all" }, "minItems": 1, "maxItems": 1 } ] }, "min_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "max_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "min_longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "max_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "additionalProperties": false, "dependentRequired": { "min_latitude": [ "max_latitude", "min_longitude", "max_longitude" ], "max_latitude": [ "min_latitude", "min_longitude", "max_longitude" ], "min_longitude": [ "min_latitude", "max_latitude", "max_longitude" ], "max_longitude": [ "min_latitude", "max_latitude", "min_longitude" ] }, "x-propertyOrder": [ [ "min_latitude", "max_latitude" ] ] } ], "description": "Filters configured for the subscription." }, "response_options": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "gridded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "degree_days" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "interpolated_point_forecast" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1 }, "variable": { "type": "string", "minLength": 1 }, "level": { "type": "integer", "minimum": 0 }, "include_distribution": { "type": "boolean" } }, "required": [ "coordinates" ], "additionalProperties": false, "dependentRequired": { "level": [ "variable" ] }, "allOf": [ { "if": { "properties": { "include_distribution": { "const": true } }, "required": [ "include_distribution" ] }, "then": { "required": [ "variable" ] } } ] } }, "required": [ "type", "options" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "tropical_cyclones" }, "options": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "geojson", "deck" ] }, "basin": { "type": "string", "enum": [ "AL", "EP", "CP", "WP", "NI", "SI", "AU", "SP" ] } }, "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "const": "event_context" }, "options": { "type": "object", "properties": { "coordinates": { "type": "string", "minLength": 1, "pattern": "^[^;]+(?:;[^;]+){0,9}$" } }, "required": [ "coordinates" ], "additionalProperties": false } }, "required": [ "type", "options" ], "additionalProperties": false } ], "description": "Attached-response configuration.", "x-present-when": "one is configured" } }, "required": [ "id", "subscription_type", "note", "filters" ] }, "description": "Active subscriptions for this webhook." }, "created_at": { "type": "string", "format": "date-time", "description": "When the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the webhook was last updated." } }, "required": [ "id", "name", "note", "url", "active", "subscriptions", "created_at", "updated_at" ] } } } }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." } } } }, "/webhooks/v1/{id}/subscriptions/{subscription_id}/ping": { "post": { "operationId": "ping_webhook_subscription", "summary": "Ping Subscription", "description": "Send a test delivery for a specific subscription.", "tags": [ "Webhooks" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/webhooks/version_1/debug/ping-subscription" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique webhook identifier." }, "description": "Unique webhook identifier." }, { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Unique subscription identifier." }, "description": "Unique subscription identifier." } ], "responses": { "204": { "description": "Successful request; no response body." }, "401": { "description": "Authentication required." }, "403": { "description": "Access denied." }, "404": { "description": "Requested data not found." }, "422": { "description": "Invalid request body." }, "502": { "description": "Upstream service error." } } } }, "/debug/v1/auth_status": { "get": { "operationId": "get_authentication_status", "summary": "Authentication Status", "description": "Check whether the API accepts your credentials.", "tags": [ "Platform" ], "externalDocs": { "description": "Endpoint Documentation", "url": "https://api.windbornesystems.com/platform/authentication/auth" }, "parameters": [], "responses": { "200": { "description": "Authenticated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authed": { "type": "boolean" }, "client_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "authed", "client_id" ] } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authed": { "type": "boolean" }, "client_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "authed", "client_id" ] } } } }, "503": { "description": "Authentication service unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authed": { "type": "boolean" }, "client_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "authed", "client_id" ] } } } } } } } }, "webhooks": { "initialization_time.available": { "post": { "operationId": "receive_initialization_time_available", "summary": "initialization_time.available", "description": "A forecast cycle is complete. An optional response contains gridded download links or interpolated point forecasts.", "security": [], "tags": [ "Webhook Deliveries" ], "externalDocs": { "url": "https://api.windbornesystems.com/webhooks/version_1/forecasts/initialization-time-available" }, "parameters": [ { "name": "Trigger-Id", "in": "header", "required": true, "description": "Matches trigger_id in the JSON payload.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this delivery attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "Webhook-Signature", "in": "header", "required": true, "description": "v1, followed by base64 HMAC-SHA256 of Trigger-Id.Webhook-Timestamp.raw_request_body, using the webhook signing secret. Verify the original body bytes before parsing JSON.", "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receive_initialization_time_available" } } } }, "responses": { "2XX": { "description": "Delivery acknowledged by the receiving service." } } } }, "forecast_hour.available": { "post": { "operationId": "receive_forecast_hour_available", "summary": "forecast_hour.available", "description": "An individual forecast output is available. An optional response contains its gridded download link or point forecasts through this forecast hour.", "security": [], "tags": [ "Webhook Deliveries" ], "externalDocs": { "url": "https://api.windbornesystems.com/webhooks/version_1/forecasts/forecast-hour-available" }, "parameters": [ { "name": "Trigger-Id", "in": "header", "required": true, "description": "Matches trigger_id in the JSON payload.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this delivery attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "Webhook-Signature", "in": "header", "required": true, "description": "v1, followed by base64 HMAC-SHA256 of Trigger-Id.Webhook-Timestamp.raw_request_body, using the webhook signing secret. Verify the original body bytes before parsing JSON.", "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receive_forecast_hour_available" } } } }, "responses": { "2XX": { "description": "Delivery acknowledged by the receiving service." } } } }, "degree_days.available": { "post": { "operationId": "receive_degree_days_available", "summary": "degree_days.available", "description": "Degree-day calculations are complete. An optional response contains both complete HDD and CDD results.", "security": [], "tags": [ "Webhook Deliveries" ], "externalDocs": { "url": "https://api.windbornesystems.com/webhooks/version_1/forecasts/degree-days-available" }, "parameters": [ { "name": "Trigger-Id", "in": "header", "required": true, "description": "Matches trigger_id in the JSON payload.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this delivery attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "Webhook-Signature", "in": "header", "required": true, "description": "v1, followed by base64 HMAC-SHA256 of Trigger-Id.Webhook-Timestamp.raw_request_body, using the webhook signing secret. Verify the original body bytes before parsing JSON.", "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receive_degree_days_available" } } } }, "responses": { "2XX": { "description": "Delivery acknowledged by the receiving service." } } } }, "tropical_cyclones.available": { "post": { "operationId": "receive_tropical_cyclones_available", "summary": "tropical_cyclones.available", "description": "Tropical cyclone products are published, including zero-storm runs. An optional response contains detail URLs; its basin filter may select fewer IDs than the notification.", "security": [], "tags": [ "Webhook Deliveries" ], "externalDocs": { "url": "https://api.windbornesystems.com/webhooks/version_1/forecasts/tropical-cyclones-available" }, "parameters": [ { "name": "Trigger-Id", "in": "header", "required": true, "description": "Matches trigger_id in the JSON payload.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this delivery attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "Webhook-Signature", "in": "header", "required": true, "description": "v1, followed by base64 HMAC-SHA256 of Trigger-Id.Webhook-Timestamp.raw_request_body, using the webhook signing secret. Verify the original body bytes before parsing JSON.", "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receive_tropical_cyclones_available" } } } }, "responses": { "2XX": { "description": "Delivery acknowledged by the receiving service." } } } }, "events.available": { "post": { "operationId": "receive_events_available", "summary": "events.available", "description": "Weather event products are published. Event IDs reflect the subscription filters and may be empty. An optional response contains point context from the notified publication.", "security": [], "tags": [ "Webhook Deliveries" ], "externalDocs": { "url": "https://api.windbornesystems.com/webhooks/version_1/forecasts/events-available" }, "parameters": [ { "name": "Trigger-Id", "in": "header", "required": true, "description": "Matches trigger_id in the JSON payload.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Webhook-Timestamp", "in": "header", "required": true, "description": "Unix seconds when this delivery attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "Webhook-Signature", "in": "header", "required": true, "description": "v1, followed by base64 HMAC-SHA256 of Trigger-Id.Webhook-Timestamp.raw_request_body, using the webhook signing secret. Verify the original body bytes before parsing JSON.", "schema": { "type": "string", "pattern": "^v1,[A-Za-z0-9+/]{43}=$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receive_events_available" } } } }, "responses": { "2XX": { "description": "Delivery acknowledged by the receiving service." } } } } }, "components": { "schemas": { "receive_initialization_time_available": { "type": "object", "properties": { "trigger_id": { "type": "string", "minLength": 1, "description": "Identifies the update that triggered this notification." }, "type": { "type": "string", "const": "initialization_time.available", "description": "The subscription type. Always `initialization_time.available` for this payload." }, "subscription_id": { "type": "integer", "minimum": 1, "description": "Identifier of the subscription that matched this model run." }, "webhook_id": { "type": "integer", "minimum": 1, "description": "Identifier of the webhook that received this delivery." }, "version": { "type": "integer", "minimum": 1, "description": "Version of the webhook payload schema." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the forecast cycle became complete." }, "webhook_note": { "type": "string", "description": "Optional webhook note.", "x-present-when": "the webhook has a note" }, "subscription_note": { "type": "string", "description": "Optional subscription note.", "x-present-when": "the subscription has a note" }, "data": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "wm-6", "wm-6-3km" ], "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "domain": { "type": "string", "const": "conus", "description": "Regional model domain. Currently `conus` for `wm-6-3km`.", "x-present-when": "the model is regional" }, "response": { "oneOf": [ { "type": "object", "properties": { "outputs": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" } }, "required": [ "forecast_hour", "url" ], "additionalProperties": false } } }, "required": [ "outputs" ], "additionalProperties": false }, { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Precipitation accumulation. The accumulation period depends on the model.", "x-unit": "mm" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" }, "p_type": { "type": [ "string", "null" ] }, "distribution": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "number", "null" ] }, "properties": { "mean": { "type": [ "number", "null" ], "description": "Ensemble mean. For `p_type`, the most probable precipitation-type code: 0 rain, 1 freezing rain, 2 ice pellets, 3 snow.", "x-available-on": [ "wm-6" ] }, "std": { "type": [ "number", "null" ], "description": "Ensemble standard deviation.", "x-available-on": [ "wm-6" ] }, "p01": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p05": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p10": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p25": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p75": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p90": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p95": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p99": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "gt_0p25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_2p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_6mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_12p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_50mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "p_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_freezing_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_ice_pellets": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_snow": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] } }, "description": "Ensemble distribution statistics for the variable.", "x-present-when": "`include_distribution=true`", "x-available-on": [ "wm-6" ] } }, "required": [ "time", "latitude", "longitude" ], "additionalProperties": { "type": [ "number", "string", "null" ], "description": "Value of the requested variable. `p_type` returns a precipitation-type name as a string; other variables return a number. Null when unavailable. Air temperature and dewpoint are returned in °C; skin and soil temperatures are returned in K." } } }, "description": "Forecasts, in the same order as the input coordinates." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Indices of requested coordinates excluded by geographic access rules.", "x-present-when": "requested coordinates are excluded" } }, "required": [ "forecasts", "initialization_time" ] } ], "description": "Endpoint response configured by `response_options`.", "x-present-when": "`response_options` is configured" } }, "required": [ "model", "initialization_time", "forecast_zero" ], "additionalProperties": false, "description": "Details of the completed forecast cycle." } }, "required": [ "trigger_id", "type", "subscription_id", "webhook_id", "version", "occurred_at", "data" ], "additionalProperties": false }, "receive_forecast_hour_available": { "type": "object", "properties": { "trigger_id": { "type": "string", "minLength": 1, "description": "Identifies the update that triggered this notification." }, "type": { "type": "string", "const": "forecast_hour.available", "description": "The subscription type. Always `forecast_hour.available` for this payload." }, "subscription_id": { "type": "integer", "minimum": 1, "description": "Identifier of the subscription that matched this forecast output." }, "webhook_id": { "type": "integer", "minimum": 1, "description": "Identifier of the webhook that received this delivery." }, "version": { "type": "integer", "minimum": 1, "description": "Version of the webhook payload schema." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the forecast output became available." }, "webhook_note": { "type": "string", "description": "Optional webhook note.", "x-present-when": "the webhook has a note" }, "subscription_note": { "type": "string", "description": "Optional subscription note.", "x-present-when": "the subscription has a note" }, "data": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "wm-6", "wm-6-3km" ], "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "domain": { "type": "string", "const": "conus", "description": "Regional model domain. Currently `conus` for `wm-6-3km`.", "x-present-when": "the model is regional" }, "forecast_hour": { "type": "integer", "minimum": 0, "description": "Hours since `forecast_zero`.", "x-unit": "hours" }, "valid_at": { "type": "string", "format": "date-time", "description": "Time at which this forecast output is valid." }, "response": { "oneOf": [ { "type": "object", "properties": { "outputs": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" } }, "required": [ "forecast_hour", "url" ], "additionalProperties": false } } }, "required": [ "outputs" ], "additionalProperties": false }, { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Precipitation accumulation. The accumulation period depends on the model.", "x-unit": "mm" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" }, "p_type": { "type": [ "string", "null" ] }, "distribution": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "number", "null" ] }, "properties": { "mean": { "type": [ "number", "null" ], "description": "Ensemble mean. For `p_type`, the most probable precipitation-type code: 0 rain, 1 freezing rain, 2 ice pellets, 3 snow.", "x-available-on": [ "wm-6" ] }, "std": { "type": [ "number", "null" ], "description": "Ensemble standard deviation.", "x-available-on": [ "wm-6" ] }, "p01": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p05": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p10": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p25": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p75": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p90": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p95": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p99": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "gt_0p25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_2p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_6mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_12p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_50mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "p_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_freezing_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_ice_pellets": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_snow": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] } }, "description": "Ensemble distribution statistics for the variable.", "x-present-when": "`include_distribution=true`", "x-available-on": [ "wm-6" ] } }, "required": [ "time", "latitude", "longitude" ], "additionalProperties": { "type": [ "number", "string", "null" ], "description": "Value of the requested variable. `p_type` returns a precipitation-type name as a string; other variables return a number. Null when unavailable. Air temperature and dewpoint are returned in °C; skin and soil temperatures are returned in K." } } }, "description": "Forecasts, in the same order as the input coordinates." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Indices of requested coordinates excluded by geographic access rules.", "x-present-when": "requested coordinates are excluded" } }, "required": [ "forecasts", "initialization_time" ] } ], "description": "Endpoint response configured by `response_options`.", "x-present-when": "`response_options` is configured" } }, "required": [ "model", "initialization_time", "forecast_zero", "forecast_hour", "valid_at" ], "additionalProperties": false, "description": "Details of the available forecast output." } }, "required": [ "trigger_id", "type", "subscription_id", "webhook_id", "version", "occurred_at", "data" ], "additionalProperties": false }, "receive_degree_days_available": { "type": "object", "properties": { "trigger_id": { "type": "string", "minLength": 1, "description": "Identifies the update that triggered this notification." }, "type": { "type": "string", "const": "degree_days.available", "description": "The subscription type. Always `degree_days.available` for this payload." }, "subscription_id": { "type": "integer", "minimum": 1, "description": "Identifier of the subscription that matched this degree day calculation." }, "webhook_id": { "type": "integer", "minimum": 1, "description": "Identifier of the webhook that received this delivery." }, "version": { "type": "integer", "minimum": 1, "description": "Version of the webhook payload schema." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the degree day calculation became available." }, "webhook_note": { "type": "string", "description": "Optional webhook note.", "x-present-when": "the webhook has a note" }, "subscription_note": { "type": "string", "description": "Optional subscription note.", "x-present-when": "the subscription has a note" }, "data": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "domain": { "type": "string", "const": "conus", "description": "Regional model domain. Currently `conus` for `wm-6-3km`.", "x-present-when": "the model is regional" }, "response": { "type": "object", "properties": { "hdds": { "type": "object", "properties": { "hdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "metadata": { "type": "object", "properties": { "model": { "type": "string" }, "subset": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" } }, "required": [ "model", "subset", "initialization_time" ] } }, "required": [ "hdd", "dates", "metadata" ] }, "cdds": { "type": "object", "properties": { "cdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "metadata": { "type": "object", "properties": { "model": { "type": "string" }, "subset": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" } }, "required": [ "model", "subset", "initialization_time" ] } }, "required": [ "cdd", "dates", "metadata" ] } }, "required": [ "hdds", "cdds" ], "additionalProperties": false, "description": "Endpoint response configured by `response_options`.", "x-present-when": "`response_options` is configured" } }, "required": [ "model", "initialization_time", "forecast_zero" ], "additionalProperties": false, "description": "Details of the available degree day calculation." } }, "required": [ "trigger_id", "type", "subscription_id", "webhook_id", "version", "occurred_at", "data" ], "additionalProperties": false }, "receive_tropical_cyclones_available": { "type": "object", "properties": { "trigger_id": { "type": "string", "minLength": 1, "description": "Identifies the update that triggered this notification." }, "type": { "type": "string", "const": "tropical_cyclones.available", "description": "The subscription type. Always `tropical_cyclones.available` for this payload." }, "subscription_id": { "type": "integer", "minimum": 1, "description": "Identifier of the subscription that matched this tropical cyclone calculation." }, "webhook_id": { "type": "integer", "minimum": 1, "description": "Identifier of the webhook that received this delivery." }, "version": { "type": "integer", "minimum": 1, "description": "Version of the webhook payload schema." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the tropical cyclone calculation became available." }, "webhook_note": { "type": "string", "description": "Optional webhook note.", "x-present-when": "the webhook has a note" }, "subscription_note": { "type": "string", "description": "Optional subscription note.", "x-present-when": "the subscription has a note" }, "data": { "type": "object", "properties": { "model": { "type": "string", "const": "wm-6", "description": "Model whose forecast output was used." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "tropical_cyclone_ids": { "type": "array", "items": { "type": "string" }, "description": "Unique tropical cyclone IDs available for this model run. Always included, even when no `response_options` value is configured. IDs are sorted lexicographically and include operational ATCF IDs and generated IDs for unmatched tracks. The array is empty when the run contains no tropical cyclones." }, "response": { "type": "object", "properties": { "tropical_cyclones": { "type": "array", "items": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "tropical_cyclone_id", "url" ], "additionalProperties": false } } }, "required": [ "tropical_cyclones" ], "additionalProperties": false, "description": "Endpoint response configured by `response_options`.", "x-present-when": "`response_options` is configured" } }, "required": [ "model", "initialization_time", "forecast_zero", "tropical_cyclone_ids" ], "additionalProperties": false, "description": "Details of the available tropical cyclone calculation." } }, "required": [ "trigger_id", "type", "subscription_id", "webhook_id", "version", "occurred_at", "data" ], "additionalProperties": false }, "receive_events_available": { "type": "object", "properties": { "trigger_id": { "type": "string", "minLength": 1, "description": "Identifies the update that triggered this notification." }, "type": { "type": "string", "const": "events.available", "description": "The subscription type. Always `events.available` for this payload." }, "subscription_id": { "type": "integer", "minimum": 1, "description": "Identifier of the subscription that matched this model run." }, "webhook_id": { "type": "integer", "minimum": 1, "description": "Identifier of the webhook that received this delivery." }, "version": { "type": "integer", "minimum": 1, "description": "Version of the webhook payload schema." }, "occurred_at": { "type": "string", "format": "date-time", "description": "UTC time when this publication became available." }, "webhook_note": { "type": "string", "description": "Optional webhook note.", "x-present-when": "the webhook has a note" }, "subscription_note": { "type": "string", "description": "Optional subscription note.", "x-present-when": "the subscription has a note" }, "data": { "type": "object", "properties": { "model": { "type": "string", "const": "wm-6", "description": "Model whose forecast output was used. Currently `wm-6`." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "event_type": { "type": "string", "enum": [ "all", "atmospheric_river", "heatwave", "coldwave", "front" ], "description": "`all` for a combined notification; otherwise the individual type that finished publishing. Subscribing to multiple specific types produces one notification per type." }, "event_ids": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "description": "Unique event IDs matching the subscription's type, valid-time, and geographic filters, sorted lexicographically. Empty when no events match." }, "response": { "type": "object", "properties": { "model": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" }, "forecast_zero": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "time": { "type": "string", "format": "date-time" }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "forecast_hour": { "type": "integer" }, "valid_time": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [] } }, "required": [ "event_type", "forecast_hour", "valid_time", "summary" ] } } }, "required": [ "latitude", "longitude", "time", "events" ] } } } }, "required": [ "model", "initialization_time", "forecast_zero", "events" ], "description": "Endpoint response configured by `response_options`.", "x-present-when": "`response_options` is configured" } }, "required": [ "model", "initialization_time", "forecast_zero", "event_type", "event_ids" ], "additionalProperties": false, "description": "Details of the available event product." } }, "required": [ "trigger_id", "type", "subscription_id", "webhook_id", "version", "occurred_at", "data" ], "additionalProperties": false }, "webhook_response_gridded": { "type": "object", "properties": { "outputs": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "forecast_hour": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" } }, "required": [ "forecast_hour", "url" ], "additionalProperties": false } } }, "required": [ "outputs" ], "additionalProperties": false }, "webhook_response_interpolated_point_forecast": { "type": "object", "properties": { "forecasts": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "When this forecast point is valid." }, "latitude": { "type": "number", "description": "Latitude.", "x-unit": "degrees" }, "longitude": { "type": "number", "description": "Longitude.", "x-unit": "degrees" }, "temperature_2m": { "type": [ "number", "null" ], "description": "Air temperature at 2 meters.", "x-unit": "°C" }, "dewpoint_2m": { "type": [ "number", "null" ], "description": "Dewpoint at 2 meters.", "x-unit": "°C" }, "precipitation": { "type": [ "number", "null" ], "description": "Precipitation accumulation. The accumulation period depends on the model.", "x-unit": "mm" }, "pressure_msl": { "type": [ "number", "null" ], "description": "Atmospheric pressure reduced to mean sea level.", "x-unit": "hPa" }, "wind_u_10m": { "type": [ "number", "null" ], "description": "Eastward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_v_10m": { "type": [ "number", "null" ], "description": "Northward wind component at 10 meters above ground level.", "x-unit": "m/s" }, "wind_speed_10m": { "type": [ "number", "null" ], "description": "Wind speed at 10 meters above ground level.", "x-unit": "m/s" }, "wind_u_100m": { "type": [ "number", "null" ], "description": "Eastward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_v_100m": { "type": [ "number", "null" ], "description": "Northward wind component at 100 meters above ground level.", "x-unit": "m/s" }, "wind_speed_100m": { "type": [ "number", "null" ], "description": "Wind speed at 100 meters above ground level.", "x-unit": "m/s" }, "p_type": { "type": [ "string", "null" ] }, "distribution": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "number", "null" ] }, "properties": { "mean": { "type": [ "number", "null" ], "description": "Ensemble mean. For `p_type`, the most probable precipitation-type code: 0 rain, 1 freezing rain, 2 ice pellets, 3 snow.", "x-available-on": [ "wm-6" ] }, "std": { "type": [ "number", "null" ], "description": "Ensemble standard deviation.", "x-available-on": [ "wm-6" ] }, "p01": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p05": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p10": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p25": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p75": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p90": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p95": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "p99": { "type": [ "number", "null" ], "description": "Ensemble percentiles.", "x-available-on": [ "wm-6" ] }, "gt_0p25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_2p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_6mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_12p5mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_25mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "gt_50mm": { "type": [ "number", "null" ], "description": "Ensemble probability of exceeding the given precipitation threshold.", "x-present-when": "a precipitation variable is requested", "x-available-on": [ "wm-6" ] }, "p_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_freezing_rain": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_ice_pellets": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] }, "p_snow": { "type": [ "number", "null" ], "description": "Ensemble probability for each precipitation type.", "x-present-when": "`variable=p_type`", "x-available-on": [ "wm-6" ] } }, "description": "Ensemble distribution statistics for the variable.", "x-present-when": "`include_distribution=true`", "x-available-on": [ "wm-6" ] } }, "required": [ "time", "latitude", "longitude" ], "additionalProperties": { "type": [ "number", "string", "null" ], "description": "Value of the requested variable. `p_type` returns a precipitation-type name as a string; other variables return a number. Null when unavailable. Air temperature and dewpoint are returned in °C; skin and soil temperatures are returned in K." } } }, "description": "Forecasts, in the same order as the input coordinates." }, "initialization_time": { "type": "string", "format": "date-time", "description": "The forecast initialization time." }, "forecast_zero": { "type": "string", "format": "date-time", "description": "Valid time of forecast hour 0." }, "filtered_coordinates": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Indices of requested coordinates excluded by geographic access rules.", "x-present-when": "requested coordinates are excluded" } }, "required": [ "forecasts", "initialization_time" ] }, "webhook_response_tropical_cyclones": { "type": "object", "properties": { "tropical_cyclones": { "type": "array", "items": { "type": "object", "properties": { "tropical_cyclone_id": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "tropical_cyclone_id", "url" ], "additionalProperties": false } } }, "required": [ "tropical_cyclones" ], "additionalProperties": false }, "webhook_response_degree_days": { "type": "object", "properties": { "hdds": { "type": "object", "properties": { "hdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "metadata": { "type": "object", "properties": { "model": { "type": "string" }, "subset": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" } }, "required": [ "model", "subset", "initialization_time" ] } }, "required": [ "hdd", "dates", "metadata" ] }, "cdds": { "type": "object", "properties": { "cdd": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "metadata": { "type": "object", "properties": { "model": { "type": "string" }, "subset": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" } }, "required": [ "model", "subset", "initialization_time" ] } }, "required": [ "cdd", "dates", "metadata" ] } }, "required": [ "hdds", "cdds" ], "additionalProperties": false }, "webhook_response_event_context": { "type": "object", "properties": { "model": { "type": "string" }, "initialization_time": { "type": "string", "format": "date-time" }, "forecast_zero": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "time": { "type": "string", "format": "date-time" }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "atmospheric_river", "heatwave", "coldwave", "front" ] }, "forecast_hour": { "type": "integer" }, "valid_time": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "summary": { "type": "object", "properties": { "peak_severity": { "type": [ "string", "null" ] }, "center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "weighted_center": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "max_area_km2": { "type": "number" }, "total_area_km2": { "type": "number" }, "area_km2": { "type": "number" }, "max_ivt": { "type": "number" }, "max_temp_c": { "type": "number" }, "min_tmin_c": { "type": "number" }, "max_threshold_deficit_c": { "type": "number" }, "classifications": { "type": "array", "items": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] } }, "classification": { "type": "string", "enum": [ "cold", "warm", "stationary", "occluded" ] }, "max_length_km": { "type": "number" }, "length_km": { "type": "number" }, "severity": { "type": "string" }, "instantaneous_severity": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "symbol_sides": { "type": "array", "items": { "type": "string", "enum": [ "left", "right" ] } }, "probability_diagnostics": { "type": "object", "properties": { "mean_probability": { "type": "number" }, "max_probability": { "type": "number" } }, "required": [ "mean_probability", "max_probability" ] } }, "required": [] } }, "required": [ "event_type", "forecast_hour", "valid_time", "summary" ] } } }, "required": [ "latitude", "longitude", "time", "events" ] } } } }, "required": [ "model", "initialization_time", "forecast_zero", "events" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "basicAuth": { "type": "http", "scheme": "basic", "description": "Client ID as username and API key as password." } } } }