{"openapi":"3.1.0","info":{"title":"Convek API","version":"0.1.0","description":"The world's first soaring-specific weather API. Thermal strength, soaring heights, convergence, cloudbase, corridor sampling - 20+ fields, updated four times daily. Model-derived forecast guidance only. Not official aviation weather.","contact":{"name":"Convek","url":"https://convek.dev","email":"hello@convek.dev"}},"servers":[{"url":"https://api.convek.dev","description":"Current environment"},{"url":"https://api.convek.dev","description":"Production"}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Your Convek API key (e.g. cvk_live_abc123)"}},"schemas":{"Status":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"environment":{"type":"string","example":"production"},"regions":{"type":"array","items":{"type":"object","properties":{"region":{"type":"string","example":"gb"},"resolution":{"type":"string","example":"4km"},"model":{"type":"string","example":"WRF"},"latest_run":{"type":["string","null"],"example":"2026-04-12T06:00:00Z"},"stale":{"type":"boolean","example":false}},"required":["region","resolution","model","latest_run","stale"]}}},"required":["status","environment","regions"]},"Regions":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/RegionCatalogItem"}}},"required":["regions"]},"RegionCatalogItem":{"type":"object","properties":{"region":{"type":"string","example":"gb"},"resolution":{"type":"string","example":"4km"},"name":{"type":"string","example":"UK 4km"},"model":{"type":"string","example":"WRF"},"resolution_km":{"type":"number","example":4},"horizon_hours":{"type":"number","example":48},"tier_minimum":{"type":"string","enum":["any","pro"],"example":"any"},"live":{"type":"boolean","example":false},"bounds":{"$ref":"#/components/schemas/RegionBounds"}},"required":["region","resolution","name","model","resolution_km","horizon_hours","tier_minimum","live","bounds"]},"RegionBounds":{"type":"object","properties":{"west":{"type":"number","example":-6},"east":{"type":"number","example":2},"south":{"type":"number","example":50},"north":{"type":"number","example":56.5}},"required":["west","east","south","north"]},"SiteForecast":{"type":"object","properties":{"sandbox":{"type":"boolean","example":false,"description":"True when response is from a sandbox key. Sandbox data is static/archived and not suitable for real use."},"valid_date":{"type":"string","example":"2026-04-12"},"valid_time":{"type":"string","example":"14:00"},"rasp_model":{"type":"string","example":"gb/4km"},"site":{"type":"object","properties":{"wstar_ms":{"type":"number","example":2.1,"description":"Thermal climb rate (m/s)"},"hglider_agl_m":{"type":"number","example":1340,"description":"Max thermalling height AGL (m)"},"hglider_msl_m":{"type":"number","example":1470,"description":"Max thermalling height MSL (m)"},"boundary_layer_m":{"type":"number","example":1520,"description":"Boundary layer depth (m)"},"convergence_ms":{"type":"number","example":0.3,"description":"Convergence vertical velocity (m/s)"},"horizontal_convergence_s1":{"type":"number","example":0.00012,"description":"Low-level horizontal convergence (s^-1). Positive values mean air is converging."},"horizontal_divergence_s1":{"type":"number","example":-0.00012,"description":"Low-level horizontal divergence (s^-1). Negative values mean converging flow."},"day_rating":{"type":"string","example":"good","description":"Soaring day rating (poor/marginal/fair/good/excellent)"},"cloudbase_agl_ft":{"type":"number","example":4800,"description":"Cloudbase AGL (ft)"},"cloudbase_msl_m":{"type":"number","example":1600,"description":"Cloudbase MSL (m)"},"cu_potential":{"type":"boolean","example":true,"description":"Cumulus cloud potential"},"od_potential":{"type":"boolean","example":false,"description":"Overdevelopment potential"},"cloud_top_m":{"type":["number","null"],"example":2400,"description":"Cloud top height MSL (m). Combined with cloudbase gives Cu depth."},"surface_temp_c":{"type":"number","example":18.2,"description":"WRF 2m temperature (°C)"},"dewpoint_2m_c":{"type":"number","example":8.4,"description":"WRF 2m dewpoint (°C). Determines cloudbase (LCL), visibility, spreadout risk."},"rh_2m_pct":{"type":"number","example":52,"description":"Relative humidity at 2m (%). High RH = hazy, poor visibility, suppressed thermals."},"thermal_trigger_temp_c":{"type":["number","null"],"example":17.5,"description":"Surface temperature at which thermals will trigger (°C). Requires vertical profile diagnostic. Null until implemented."},"rain_total_mm":{"type":"number","example":0,"description":"Total precipitation (mm)"},"cape_jkg":{"type":["number","null"],"example":120,"description":"CAPE (J/kg). Null until implemented."},"surface_wind_speed_ms":{"type":"number","example":3.1,"description":"WRF 10m wind speed (m/s). Resolves terrain channelling, sea breeze, valley flows that global models miss."},"surface_wind_dir_deg":{"type":"number","example":240,"description":"WRF 10m wind direction (degrees)"},"wind_925_speed_ms":{"type":"number","example":5.2,"description":"Wind speed at 925hPa (~750m, m/s)"},"wind_925_dir_deg":{"type":"number","example":250,"description":"Wind direction at 925hPa (degrees)"},"wind_850_speed_ms":{"type":"number","example":6.8,"description":"Wind speed at 850hPa (~1500m, m/s)"},"wind_850_dir_deg":{"type":"number","example":255,"description":"Wind direction at 850hPa (degrees)"},"wind_800_speed_ms":{"type":"number","example":7.4,"description":"Wind speed at 800hPa (~2000m, m/s)"},"wind_800_dir_deg":{"type":"number","example":260,"description":"Wind direction at 800hPa (degrees)"},"wind_700_speed_ms":{"type":"number","example":8.5,"description":"Wind speed at 700hPa (~3000m, m/s)"},"wind_700_dir_deg":{"type":"number","example":265,"description":"Wind direction at 700hPa (degrees)"},"shear_surface_925_ms":{"type":"number","example":3.4,"description":"Wind shear magnitude surface→925hPa (m/s). Pre-computed launch-level shear from WRF."},"shear_surface_925_dir_deg":{"type":"number","example":45,"description":"Wind shear direction surface→925hPa (degrees). Veering/backing indicator."},"bowen_ratio":{"type":["number","null"],"example":1.8,"description":"Bowen ratio (sensible/latent heat). High = dry ground, strong thermals. Low = wet/green, weak thermals."}},"required":["wstar_ms","hglider_agl_m","hglider_msl_m","boundary_layer_m","convergence_ms","horizontal_convergence_s1","horizontal_divergence_s1","day_rating","cloudbase_agl_ft","cloudbase_msl_m","cu_potential","od_potential","cloud_top_m","surface_temp_c","dewpoint_2m_c","rh_2m_pct","thermal_trigger_temp_c","rain_total_mm","cape_jkg","surface_wind_speed_ms","surface_wind_dir_deg","wind_925_speed_ms","wind_925_dir_deg","wind_850_speed_ms","wind_850_dir_deg","wind_800_speed_ms","wind_800_dir_deg","wind_700_speed_ms","wind_700_dir_deg","shear_surface_925_ms","shear_surface_925_dir_deg","bowen_ratio"]}},"required":["valid_date","valid_time","rasp_model","site"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"},"message":{"type":"string","example":"Invalid or missing API key"}},"required":["error","message"]},"PointForecastDay":{"type":"object","properties":{"sandbox":{"type":"boolean","example":false,"description":"True when response is from a sandbox key. Sandbox data is static/archived and not suitable for real use."},"valid_date":{"type":"string","example":"2026-04-12"},"rasp_model":{"type":"string","example":"gb/4km"},"hours":{"type":"array","items":{"type":"object","properties":{"valid_time":{"type":"string","example":"14:00"},"site":{"type":"object","properties":{"wstar_ms":{"type":"number","example":2.1,"description":"Thermal climb rate (m/s)"},"hglider_agl_m":{"type":"number","example":1340,"description":"Max thermalling height AGL (m)"},"hglider_msl_m":{"type":"number","example":1470,"description":"Max thermalling height MSL (m)"},"boundary_layer_m":{"type":"number","example":1520,"description":"Boundary layer depth (m)"},"convergence_ms":{"type":"number","example":0.3,"description":"Convergence vertical velocity (m/s)"},"horizontal_convergence_s1":{"type":"number","example":0.00012,"description":"Low-level horizontal convergence (s^-1). Positive values mean air is converging."},"horizontal_divergence_s1":{"type":"number","example":-0.00012,"description":"Low-level horizontal divergence (s^-1). Negative values mean converging flow."},"day_rating":{"type":"string","example":"good","description":"Soaring day rating (poor/marginal/fair/good/excellent)"},"cloudbase_agl_ft":{"type":"number","example":4800,"description":"Cloudbase AGL (ft)"},"cloudbase_msl_m":{"type":"number","example":1600,"description":"Cloudbase MSL (m)"},"cu_potential":{"type":"boolean","example":true,"description":"Cumulus cloud potential"},"od_potential":{"type":"boolean","example":false,"description":"Overdevelopment potential"},"cloud_top_m":{"type":["number","null"],"example":2400,"description":"Cloud top height MSL (m). Combined with cloudbase gives Cu depth."},"surface_temp_c":{"type":"number","example":18.2,"description":"WRF 2m temperature (°C)"},"dewpoint_2m_c":{"type":"number","example":8.4,"description":"WRF 2m dewpoint (°C). Determines cloudbase (LCL), visibility, spreadout risk."},"rh_2m_pct":{"type":"number","example":52,"description":"Relative humidity at 2m (%). High RH = hazy, poor visibility, suppressed thermals."},"thermal_trigger_temp_c":{"type":["number","null"],"example":17.5,"description":"Surface temperature at which thermals will trigger (°C). Requires vertical profile diagnostic. Null until implemented."},"rain_total_mm":{"type":"number","example":0,"description":"Total precipitation (mm)"},"cape_jkg":{"type":["number","null"],"example":120,"description":"CAPE (J/kg). Null until implemented."},"surface_wind_speed_ms":{"type":"number","example":3.1,"description":"WRF 10m wind speed (m/s). Resolves terrain channelling, sea breeze, valley flows that global models miss."},"surface_wind_dir_deg":{"type":"number","example":240,"description":"WRF 10m wind direction (degrees)"},"wind_925_speed_ms":{"type":"number","example":5.2,"description":"Wind speed at 925hPa (~750m, m/s)"},"wind_925_dir_deg":{"type":"number","example":250,"description":"Wind direction at 925hPa (degrees)"},"wind_850_speed_ms":{"type":"number","example":6.8,"description":"Wind speed at 850hPa (~1500m, m/s)"},"wind_850_dir_deg":{"type":"number","example":255,"description":"Wind direction at 850hPa (degrees)"},"wind_800_speed_ms":{"type":"number","example":7.4,"description":"Wind speed at 800hPa (~2000m, m/s)"},"wind_800_dir_deg":{"type":"number","example":260,"description":"Wind direction at 800hPa (degrees)"},"wind_700_speed_ms":{"type":"number","example":8.5,"description":"Wind speed at 700hPa (~3000m, m/s)"},"wind_700_dir_deg":{"type":"number","example":265,"description":"Wind direction at 700hPa (degrees)"},"shear_surface_925_ms":{"type":"number","example":3.4,"description":"Wind shear magnitude surface→925hPa (m/s). Pre-computed launch-level shear from WRF."},"shear_surface_925_dir_deg":{"type":"number","example":45,"description":"Wind shear direction surface→925hPa (degrees). Veering/backing indicator."},"bowen_ratio":{"type":["number","null"],"example":1.8,"description":"Bowen ratio (sensible/latent heat). High = dry ground, strong thermals. Low = wet/green, weak thermals."}},"required":["wstar_ms","hglider_agl_m","hglider_msl_m","boundary_layer_m","convergence_ms","horizontal_convergence_s1","horizontal_divergence_s1","day_rating","cloudbase_agl_ft","cloudbase_msl_m","cu_potential","od_potential","cloud_top_m","surface_temp_c","dewpoint_2m_c","rh_2m_pct","thermal_trigger_temp_c","rain_total_mm","cape_jkg","surface_wind_speed_ms","surface_wind_dir_deg","wind_925_speed_ms","wind_925_dir_deg","wind_850_speed_ms","wind_850_dir_deg","wind_800_speed_ms","wind_800_dir_deg","wind_700_speed_ms","wind_700_dir_deg","shear_surface_925_ms","shear_surface_925_dir_deg","bowen_ratio"]}},"required":["valid_time","site"]},"description":"All forecast hours available for the requested date at the nearest model grid point."}},"required":["valid_date","rasp_model","hours"]},"GridResponse":{"type":"object","properties":{"sandbox":{"type":"boolean","example":false,"description":"True when response is from a sandbox key. Sandbox data is static/archived and not suitable for real use."},"valid_date":{"type":"string","example":"2026-04-12"},"valid_time":{"type":"string","example":"14:00"},"rasp_model":{"type":"string","example":"gb/4km"},"field":{"$ref":"#/components/schemas/GridField"},"units":{"type":["string","null"],"example":"m/s","description":"Units for the requested field. Null when the field is categorical."},"value_type":{"type":"string","enum":["number","string"],"example":"number","description":"Payload value type for the grid cells."},"bounds":{"type":"object","properties":{"west":{"type":"number","example":-4.5},"east":{"type":"number","example":-1.2},"south":{"type":"number","example":50.8},"north":{"type":"number","example":52.6}},"required":["west","east","south","north"]},"grid_shape":{"type":"object","properties":{"south_north":{"type":"number","example":30},"west_east":{"type":"number","example":42}},"required":["south_north","west_east"]},"grid_lat":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"Latitude at each returned grid cell centre."},"grid_lon":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"Longitude at each returned grid cell centre."},"data":{"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}]}},"description":"Requested field values aligned to grid_lat/grid_lon."}},"required":["valid_date","valid_time","rasp_model","field","units","value_type","bounds","grid_shape","grid_lat","grid_lon","data"]},"GridField":{"type":"string","enum":["wstar_ms","boundary_layer_m","convergence_ms","horizontal_convergence_s1","horizontal_divergence_s1","day_rating","cloudbase_agl_ft","cloudbase_msl_m","surface_wind_speed_ms","surface_wind_dir_deg","wind_925_speed_ms","wind_925_dir_deg","rain_total_mm"]},"CorridorForecast":{"type":"object","properties":{"sandbox":{"type":"boolean","example":false,"description":"True when response is from a sandbox key."},"valid_date":{"type":"string","example":"2026-04-12"},"rasp_model":{"type":"string","example":"gb/4km"},"route":{"type":"object","properties":{"launch_lat":{"type":"number","example":51.94},"launch_lon":{"type":"number","example":-2.08},"bearing_deg":{"type":"number","example":45},"max_distance_km":{"type":"number","example":100},"sample_spacing_km":{"type":"number","example":10},"time_aware":{"type":"boolean","example":false}},"required":["launch_lat","launch_lon","bearing_deg","max_distance_km","sample_spacing_km","time_aware"]},"samples":{"type":"array","items":{"type":"object","properties":{"along_track_km":{"type":"number","example":30,"description":"Distance from launch along the route (km)"},"lat":{"type":"number","example":52.13,"description":"Sample point latitude"},"lon":{"type":"number","example":-1.87,"description":"Sample point longitude"},"terrain_elevation_m":{"type":"number","example":145,"description":"Terrain elevation at sample point (m MSL)"},"estimated_arrival":{"type":"string","example":"13:45","description":"Estimated arrival time (HH:MM UTC). Only present when time_aware=true."},"valid_time":{"type":"string","example":"14:00","description":"Forecast hour used for this sample"},"wstar_ms":{"type":"number","example":2.1,"description":"Thermal climb rate (m/s)"},"hglider_agl_m":{"type":"number","example":1340,"description":"Max thermalling height AGL (m)"},"hglider_msl_m":{"type":"number","example":1470,"description":"Max thermalling height MSL (m)"},"boundary_layer_m":{"type":"number","example":1520,"description":"Boundary layer depth (m)"},"convergence_ms":{"type":"number","example":0.3,"description":"Convergence vertical velocity (m/s)"},"horizontal_convergence_s1":{"type":"number","example":0.00012,"description":"Low-level horizontal convergence (s^-1). Positive values mean air is converging."},"horizontal_divergence_s1":{"type":"number","example":-0.00012,"description":"Low-level horizontal divergence (s^-1). Negative values mean converging flow."},"day_rating":{"type":"string","example":"good","description":"Soaring day rating"},"cloudbase_agl_ft":{"type":"number","example":4800,"description":"Cloudbase AGL (ft)"},"cloudbase_msl_m":{"type":"number","example":1600,"description":"Cloudbase MSL (m)"},"cu_potential":{"type":"boolean","example":true,"description":"Cumulus cloud potential"},"od_potential":{"type":"boolean","example":false,"description":"Overdevelopment potential"},"surface_wind_speed_ms":{"type":"number","example":3.1,"description":"WRF 10m wind speed (m/s)"},"surface_wind_dir_deg":{"type":"number","example":240,"description":"WRF 10m wind direction (degrees)"},"wind_925_speed_ms":{"type":"number","example":5.2,"description":"Wind speed at 925hPa (m/s)"},"wind_925_dir_deg":{"type":"number","example":250,"description":"Wind direction at 925hPa (degrees)"}},"required":["along_track_km","lat","lon","terrain_elevation_m","valid_time","wstar_ms","hglider_agl_m","hglider_msl_m","boundary_layer_m","convergence_ms","horizontal_convergence_s1","horizontal_divergence_s1","day_rating","cloudbase_agl_ft","cloudbase_msl_m","cu_potential","od_potential","surface_wind_speed_ms","surface_wind_dir_deg","wind_925_speed_ms","wind_925_dir_deg"]}}},"required":["valid_date","rasp_model","route","samples"]},"CorridorRequest":{"type":"object","properties":{"region":{"type":"string","example":"gb","description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions."},"resolution":{"type":"string","example":"4km","description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region."},"launch_lat":{"type":"number","minimum":-90,"maximum":90,"example":51.94,"description":"Launch site latitude (decimal degrees, -90 to 90)"},"launch_lon":{"type":"number","minimum":-180,"maximum":180,"example":-2.08,"description":"Launch site longitude (decimal degrees, -180 to 180)"},"bearing_deg":{"type":"number","minimum":0,"maximum":360,"example":45,"description":"Route bearing (degrees clockwise from north, 0-360)"},"max_distance_km":{"type":"number","minimum":1,"maximum":500,"example":100,"description":"Maximum route distance (km, 1-500)"},"sample_spacing_km":{"type":"number","minimum":1,"maximum":50,"example":10,"description":"Distance between sample points (km, 1-50)"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-12","description":"Forecast date (YYYY-MM-DD). Defaults to today."},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"14:00","description":"Forecast time (HH:MM UTC). Defaults to peak soaring hour."},"time_aware":{"type":"boolean","default":false,"example":false,"description":"If true, calculates arrival time at each sample point and returns the forecast for that time."},"launch_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"12:00","description":"Launch time (HH:MM UTC). Required if time_aware=true."},"ground_speed_kmh":{"type":"number","minimum":1,"maximum":300,"example":40,"description":"Expected ground speed (km/h). Required if time_aware=true."}},"required":["region","resolution","launch_lat","launch_lon","bearing_deg","max_distance_km","sample_spacing_km"]},"SoundingForecast":{"type":"object","properties":{"sandbox":{"type":"boolean","example":false,"description":"True when response is from a sandbox key. Sandbox data is static/archived and not suitable for real use."},"valid_date":{"type":"string","example":"2026-04-12"},"valid_time":{"type":"string","example":"14:00"},"rasp_model":{"type":"string","example":"gb/4km"},"surface_elevation_m":{"type":"number","example":143,"description":"Surface elevation at the selected grid point (m MSL)"},"levels":{"type":"array","items":{"type":"object","properties":{"altitude_m":{"type":"number","example":312,"description":"Altitude above mean sea level at this pressure level (m)"},"pressure_hpa":{"type":"number","example":925,"description":"Pressure level (hPa)"},"temperature_c":{"type":"number","example":12.4,"description":"Air temperature (°C)"},"dewpoint_c":{"type":"number","example":8.1,"description":"Dewpoint (°C)"},"wind_speed_ms":{"type":"number","example":6.4,"description":"Wind speed (m/s)"},"wind_dir_deg":{"type":"number","example":238,"description":"Wind direction (degrees)"}},"required":["altitude_m","pressure_hpa","temperature_c","dewpoint_c","wind_speed_ms","wind_dir_deg"]},"description":"Vertical profile values from low level to upper level."}},"required":["valid_date","valid_time","rasp_model","surface_elevation_m","levels"]}},"parameters":{}},"paths":{"/v1/status":{"get":{"tags":["System"],"summary":"Service status","description":"Check which forecast regions are currently live and when they were last updated.","responses":{"200":{"description":"Current service status and live regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/regions":{"get":{"tags":["System"],"summary":"Configured regions","description":"List every configured region+resolution pair, including whether it is currently live.","responses":{"200":{"description":"Configured region and resolution catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Regions"}}}}}}},"/v1/site":{"get":{"tags":["Forecasts"],"summary":"Point forecast","description":"Get a soaring weather forecast for a specific lat/lon point. Returns thermal strength, soaring heights, cloudbase, wind, and 15+ other fields.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"gb","description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions."},"required":true,"description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions.","name":"region","in":"query"},{"schema":{"type":"string","example":"4km","description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region."},"required":true,"description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region.","name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"51.94","description":"Latitude (decimal degrees, -90 to 90)"},"required":true,"description":"Latitude (decimal degrees, -90 to 90)","name":"lat","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"-2.08","description":"Longitude (decimal degrees, -180 to 180)"},"required":true,"description":"Longitude (decimal degrees, -180 to 180)","name":"lon","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-12","description":"Forecast date (YYYY-MM-DD). Defaults to today."},"required":false,"description":"Forecast date (YYYY-MM-DD). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"14:00","description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour."},"required":false,"description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour.","name":"time","in":"query"}],"responses":{"200":{"description":"Forecast data for the requested point","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteForecast"}}}},"400":{"description":"Invalid query parameters or coordinates outside region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier too low for requested resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Region+resolution not yet live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Forecast backend not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Auth service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/forecast":{"get":{"tags":["Forecasts"],"summary":"Full-day point forecast","description":"Get all forecast hours for a specific lat/lon point on a single date. Returns the same field set as /v1/site, but as an hourly array for charts, map popups, and day planning.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"gb","description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions."},"required":true,"description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions.","name":"region","in":"query"},{"schema":{"type":"string","example":"4km","description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region."},"required":true,"description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region.","name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"51.94","description":"Latitude (decimal degrees, -90 to 90)"},"required":true,"description":"Latitude (decimal degrees, -90 to 90)","name":"lat","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"-2.08","description":"Longitude (decimal degrees, -180 to 180)"},"required":true,"description":"Longitude (decimal degrees, -180 to 180)","name":"lon","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-12","description":"Forecast date (YYYY-MM-DD). Defaults to today."},"required":false,"description":"Forecast date (YYYY-MM-DD). Defaults to today.","name":"date","in":"query"}],"responses":{"200":{"description":"Hourly forecast data for the requested point and date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointForecastDay"}}}},"400":{"description":"Invalid query parameters or coordinates outside region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier too low for requested resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Region+resolution not yet live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Forecast backend not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Auth service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/grid":{"get":{"tags":["Forecasts"],"summary":"Grid field slice","description":"Get a bounded gridded field slice for one forecast hour. Intended for maps, embeds, club pages, and developer integrations. Full-domain pulls are not supported on this endpoint.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"gb","description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions."},"required":true,"description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions.","name":"region","in":"query"},{"schema":{"type":"string","example":"4km","description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region."},"required":true,"description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region.","name":"resolution","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/GridField"},{"example":"wstar_ms","description":"Grid field to return."}]},"required":true,"description":"Grid field to return.","name":"field","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-12","description":"Forecast date (YYYY-MM-DD). Defaults to today."},"required":false,"description":"Forecast date (YYYY-MM-DD). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"14:00","description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour."},"required":false,"description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour.","name":"time","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"-4.50","description":"Required west bound for a bounded grid slice."},"required":true,"description":"Required west bound for a bounded grid slice.","name":"west","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"-1.20","description":"Required east bound for a bounded grid slice."},"required":true,"description":"Required east bound for a bounded grid slice.","name":"east","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"50.80","description":"Required south bound for a bounded grid slice."},"required":true,"description":"Required south bound for a bounded grid slice.","name":"south","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"52.60","description":"Required north bound for a bounded grid slice."},"required":true,"description":"Required north bound for a bounded grid slice.","name":"north","in":"query"}],"responses":{"200":{"description":"Grid slice for the requested field and forecast hour","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridResponse"}}}},"400":{"description":"Invalid query parameters or bounds outside region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier too low for the grid endpoint or requested resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Region+resolution not yet live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Forecast backend not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Auth service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/corridor":{"post":{"tags":["Forecasts"],"summary":"Corridor forecast","description":"Get weather samples along a route defined by a launch point, bearing, and distance. Optionally time-aware: calculates arrival time at each sample and returns the forecast for that hour.","security":[{"Bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorridorRequest"}}}},"responses":{"200":{"description":"Forecast samples along the corridor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorridorForecast"}}}},"400":{"description":"Invalid request body or launch point outside region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier too low for requested resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Region+resolution not yet live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Forecast backend not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Auth service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sounding":{"get":{"tags":["Forecasts"],"summary":"Sounding profile","description":"Get the raw vertical profile values for a specific lat/lon point. Returns pressure, altitude, temperature, dewpoint, wind speed, and wind direction by level.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"gb","description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions."},"required":true,"description":"Region code (e.g. gb, ch, si, at, cz, de). See /v1/regions for configured regions.","name":"region","in":"query"},{"schema":{"type":"string","example":"4km","description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region."},"required":true,"description":"Grid resolution (e.g. 4km or 2km). See /v1/regions for configured resolutions per region.","name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"51.94","description":"Latitude (decimal degrees, -90 to 90)"},"required":true,"description":"Latitude (decimal degrees, -90 to 90)","name":"lat","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"-2.08","description":"Longitude (decimal degrees, -180 to 180)"},"required":true,"description":"Longitude (decimal degrees, -180 to 180)","name":"lon","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-04-12","description":"Forecast date (YYYY-MM-DD). Defaults to today."},"required":false,"description":"Forecast date (YYYY-MM-DD). Defaults to today.","name":"date","in":"query"},{"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","example":"14:00","description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour."},"required":false,"description":"Forecast time (HH:MM UTC, 00:00-23:59). Defaults to peak soaring hour.","name":"time","in":"query"}],"responses":{"200":{"description":"Sounding profile data for the requested point","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoundingForecast"}}}},"400":{"description":"Invalid query parameters or coordinates outside region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier too low for requested resolution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Region+resolution not yet live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Forecast backend not implemented yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Auth service temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}