A packet. Not a model dump.
Wind at native heights with provenance on every number, and a deterministic decision against the limits you pass. The language model never produces these values. Missing data is returned as missing, never as zero.
Quickstart: three calls
Create a key in Account, then make these three calls. Replace the key and coordinates. The first finds the coordinates, the second reads the wind there, the third asks for a decision against your own limit.
curl "https://thewindagent.com/api/geocode?q=Clonmel"
curl -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"
curl -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/decision?lat=51.834&lon=-8.322&mode=crane&maxGustMph=27"
Step 1 uses the unauthenticated geocoder and returns latitude and longitude for a place name. Steps 2 and 3 need your key. Each response includes X-RateLimit-Remainingso you can see how much of the day is left.
Authentication
Create a key in Account → API keys (Pro, Ops and Enterprise). Keys look like wa_live_…, are shown once, and can be revoked at any time. Send the key as a bearer token. CORS is open, but keep keys server-side.
Authorization: Bearer wa_live_<32 base64url characters>
GET /api/v1/wind
Seven days of hourly wind for a point. Speeds in mph, directions in degrees the wind blows from. Gust is the model 10 m gust; there is no derived gust aloft. Times are site-local wall clock in location.timezone.
| Param | Type | Notes |
|---|---|---|
| lat | number | −90 … 90, required |
| lon | number | −180 … 180, required |
curl -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"
{
"location": { "latitude": 52.3387, "longitude": -7.6553, "elevationM": 175, "timezone": "Europe/Dublin" },
"current": {
"time": "2026-10-03T16:00", // site-local wall clock
"speedMph": 5.1, "gustMph": 11, "directionDeg": 204, // 10 m, direction FROM
"agreementScore": 78, "agreementCount": 3,
"heights": {
"h80": { "speedMph": 8.6, "directionDeg": 200 },
"h120": { "speedMph": 8.9, "directionDeg": 200 },
"h180": { "speedMph": 8.4, "directionDeg": 200 }
}
},
"hourly": [ /* 168 hours, same shape */ ],
"provenance": {
"kind": "forecast", "source": "Open-Meteo modelled Best Match",
"models": ["ICON", "GFS", "ECMWF IFS"], "heightsM": [10, 80, 120, 180],
"modelRuns": [{ "model": "ecmwf_ifs025", "runInitialisedAt": "2026-10-03T06:00:00.000Z", ... }],
"coverage": { "requestedHours": 168, "returnedHours": 168, "droppedIncompleteHours": 0 }
}
}GET /api/v1/decision
The deterministic decision for the current hour plus the candidate windows in the forecast where your limits hold. The engine is the same code the instrument runs; the agent only explains its output.
| Param | Type | Notes |
|---|---|---|
| lat, lon | number | required |
| mode | enum | golf · crane · spray · marine · drone · motorsport · events (required) |
| maxGustMph | number | default 25 — set it from your own document |
| minWindMph | number | default 3 |
| maxWindMph | number | default 10 |
| bearingDeg | number | 0 … 360, default 90 (route/hole bearing for cross/headwind modes) |
curl -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/decision?lat=51.834&lon=-8.322&mode=crane&maxGustMph=27"
{
"mode": "crane",
"config": { "maxGustMph": 27, "minWindMph": 3, "maxWindMph": 10, "bearingDeg": 90 },
"timezone": "Europe/Dublin",
"current": {
"tone": "good" | "watch" | "stop",
"verdict": "…", "score": 0-100,
"summary": "…", "recommendation": "…", "threshold": "…",
"drivers": ["…"]
},
"candidateWindows": [
{ "start": "2026-10-04T07:00", "end": "2026-10-04T13:00", "hours": 6 } // site-local, end exclusive
],
"provenance": {
"decisionEngine": "The Wind Agent deterministic rules (analyzeImpact)",
"windowsNote": "Windows are site-local times; end is exclusive. Modelled forecast, not an on-site observation.",
…forecast provenance
}
}Ensemble exceedance (p10 / p50 / p90 / pExceed with member counts per model) is served to the instrument from GFS, ECMWF IFS ENS and ICON-EPS members. Probabilities are raw member fractions, not calibrated; hours with fewer than 10 members return pExceed: null, insufficient: true. Models are never silently substituted. Ensemble on the public v1 API is not yet exposed.
Endpoint reference
25 operations across 22 paths, generated from openapi.yaml. The two /api/v1 endpoints are the supported, rate-limited public API. The rest are the endpoints the instrument itself calls. They are documented because they are useful and stable in practice, but only /api/v1 carries a versioning promise.
Public API (bearer key)
GET /api/v1/wind
Seven-day wind evidence (public API, bearer key).
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
curl \ -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"
{
"location": { "latitude": 52.3387, "longitude": -7.6553, "elevationM": 175, "timezone": "Europe/Dublin" },
"current": { "time": "2026-10-03T16:00", "speedMph": 5.1, "gustMph": 11, "directionDeg": 204,
"agreementScore": 78, "agreementCount": 3,
"heights": { "h80": { "speedMph": 8.6, "directionDeg": 200 }, "h120": { "speedMph": 8.9, "directionDeg": 200 }, "h180": { "speedMph": 8.4, "directionDeg": 200 } } },
"hourly": [ /* 168 hours, same shape */ ],
"provenance": { "kind": "forecast", "source": "Open-Meteo modelled Best Match", "heightsM": [10, 80, 120, 180],
"coverage": { "requestedHours": 168, "returnedHours": 168, "droppedIncompleteHours": 0 } }
}- 200 Same payload as /api/wind
- 401 Missing
- 403 Plan does not include API access
- 429 Daily cap reached (pro 1,000; ops 10,000; enterprise 100,000 per UTC day)
GET /api/v1/decision
Deterministic decision for now plus candidate windows (public API, bearer key).
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| mode | query | golf | crane | spray | marine | drone | motorsport | events | required |
| maxGustMph | query | number | optional · default 25 |
| minWindMph | query | number | optional · default 3 |
| maxWindMph | query | number | optional · default 10 |
| bearingDeg | query | number | optional · default 90 |
curl \ -H "Authorization: Bearer wa_live_YOUR_KEY" \ "https://thewindagent.com/api/v1/decision?lat=51.834&lon=-8.322&mode=crane&maxGustMph=27"
{
"mode": "crane", "config": { "maxGustMph": 27, "minWindMph": 3, "maxWindMph": 10, "bearingDeg": 90 }, "timezone": "Europe/Dublin",
"current": { "tone": "watch", "verdict": "…", "score": 61, "summary": "…", "recommendation": "…", "threshold": "…", "drivers": ["…"] },
"candidateWindows": [ { "start": "2026-10-04T07:00", "end": "2026-10-04T13:00", "hours": 6 } ],
"provenance": { "decisionEngine": "The Wind Agent deterministic rules (analyzeImpact)" }
}- 200 `{ current, candidateWindows: [{start,end,hours}], provenance, ... }` — site-local times, end exclusive
- 400 Invalid parameters
- 401 Missing or invalid key
- 429 Daily cap reached
- 502 Forecast source unavailable
Instrument endpoints (no key)
Read endpoints that need no key. They are cached, not covered by plan rate limits and not versioned: build integrations on /api/v1.
GET /api/wind
Get seven-day wind evidence and model agreement.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| days | query | integer | optional · 7…16, default 7 · Forecast horizon in days (v2, additive). Hours missing any core field are omitted and listed in provenance.coverage. |
curl \ "https://thewindagent.com/api/wind?lat=52.3389&lon=-7.6489&days=7"
{
"location": { "latitude": 52.3387, "longitude": -7.6553, "elevationM": 175, "timezone": "Europe/Dublin" },
"current": { "time": "2026-10-03T16:00", "speedMph": 5.1, "gustMph": 11, "directionDeg": 204,
"agreementScore": 78, "agreementCount": 3,
"heights": { "h80": { "speedMph": 8.6, "directionDeg": 200 }, "h120": { "speedMph": 8.9, "directionDeg": 200 }, "h180": { "speedMph": 8.4, "directionDeg": 200 } } },
"hourly": [ /* 168 hours, same shape */ ],
"provenance": { "kind": "forecast", "source": "Open-Meteo modelled Best Match", "heightsM": [10, 80, 120, 180],
"coverage": { "requestedHours": 168, "returnedHours": 168, "droppedIncompleteHours": 0 } }
}- 200 Current and hourly wind evidence (modelled forecast, not observation). Cache-Control public, max-age=600.
- 400 Invalid coordinates
- 502 Forecast source unavailable
GET /api/ensemble
Ensemble member spread and threshold exceedance fractions.
Raw GEFS 0.25°, ECMWF IFS ENS 0.25° and ICON-EPS member spread from the Open-Meteo Ensemble API. pExceed is the uncalibrated fraction of members at or above `limit`, not a calibrated probability. Hours with fewer than 10 members return pExceed null and insufficient true. Cache-Control max-age=900.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| metric | query | gust | speed | optional · default gust |
| height | query | integer | optional · default 10 · Metres above ground. gust supports 10 only; speed supports 10, 80, 100, 120 where the upstream has member data. |
| limit | query | number | optional · 0… · Threshold in mph for pExceed / pExceedByModel. |
| days | query | integer | optional · 1…7, default 3 |
curl \ "https://thewindagent.com/api/ensemble?lat=52.3389&lon=-7.6489&metric=speed&height=80&limit=20&days=2"
{
"metric": "speed", "heightM": 80, "unit": "mph", "limitMph": 20,
"hours": [ { "time": "2026-10-03T16:00", "memberCount": 40, "perModelCounts": { "icon_seamless": 40 },
"p10": 9.1, "p50": 13.4, "p90": 19.8, "pExceed": 0.05, "insufficient": false }, … ],
"models": [ { "id": "icon_seamless", "members": 40, "attribution": "DWD ICON-EPS via Open-Meteo (CC BY 4.0)" } ],
"provenance": { "kind": "ensemble_forecast", "source": "Open-Meteo Ensemble API", "note": "pExceed is an uncalibrated member fraction." }
}- 200 Per-hour member percentiles
- 400 Invalid parameters
- 422 Height/metric combination unsupported or no members at that height
- 502 Ensemble source unavailable
GET /api/climate
ERA5 reanalysis climatology for the calendar window.
±15 days around `date` for each of the last 10 years (ERA5 via Open-Meteo archive). Partial year failures are tolerated and reported in yearsCovered / yearsFailed. Cache-Control max-age=86400.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| date | query | string (date) | optional |
| forecastGustMph | query | number | optional |
| forecastSpeedMph | query | number | optional |
curl \ "https://thewindagent.com/api/climate?lat=52.3389&lon=-7.6489&date=2026-10-03"
{
"date": "2026-10-03",
"windRose": [ { "sector": "SW", "freqPct": 17.2, "meanSpeedMph": 13.8, "maxGustMph": 52 }, … ],
"calmPct": 3.1,
"speedPercentiles": { "p10": 4.2, "p50": 11.0, "p90": 21.5, "p99": 33.0 },
"anomaly": { "speedPercentile": 62, "label": "normal" },
"provenance": { "kind": "reanalysis_climatology", "source": "ERA5 via Open-Meteo archive" }
}- 200 Wind rose, percentiles and optional anomaly
- 400 Invalid parameters
- 502 Climatology source unavailable for every year
GET /api/geocode
Find places.
| Param | In | Type | Notes |
|---|---|---|---|
| q | query | string | required |
curl \ "https://thewindagent.com/api/geocode?q=Clonmel"
{ "results": [ { "name": "Clonmel", "area": "County Tipperary", "country": "Ireland", "latitude": 52.3555, "longitude": -7.7033 }, … ] }- 200 Matching places
POST /api/agent
Explain a deterministic wind decision.
The agent may explain supplied facts but does not create the verdict.
| Param | In | Type | Notes |
|---|---|---|---|
| question | body | string | required |
| mode | body | golf | crane | spray | marine | drone | motorsport | events | required |
| place | body | object | required |
| wind | body | any | required |
| decision | body | object | required |
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "question": "Is the wind steady this afternoon?", "mode": "crane", "place": { "name": "Cork Docks", "latitude": 51.9, "longitude": -8.4 }, "wind": { "time": "2026-10-03T16:00", "speedMph": 5.1, "gustMph": 11, "directionDeg": 204, "agreementScore": 78, "agreementCount": 3, "heights": { "h80": { "speedMph": 8.6, "directionDeg": 200 }, "h120": { "speedMph": 8.9, "directionDeg": 200 }, "h180": { "speedMph": 8.4, "directionDeg": 200 } } }, "decision": { "tone": "watch" } }' \
"https://thewindagent.com/api/agent"{ "reply": "Gusts reach 24 mph at 15:00 against your 27 mph limit …", "provider": "grok", "engine": "grok", "unverified": [] }- 200 Grounded explanation
- 400 Invalid request
- 429 Rate limit reached
GET /api/observations
Measured wind from nearby METAR stations and NDBC buoys (nearest 8).
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required |
| lon | query | number | required |
| radiusKm | query | number | optional · 25…400, default 150 |
curl \ "https://thewindagent.com/api/observations?lat=52.3389&lon=-7.6489&radiusKm=150"
{
"stations": [ { "id": "EIWF", "name": "Waterford", "kind": "metar", "distanceKm": 41.2, "speedMph": 6.9, "gustMph": null, "directionDeg": 210, "ageMinutes": 18 }, … ],
"summary": { "count": 8 }, "provenance": [ { "source": "aviationweather.gov METAR" } ], "warnings": []
}- 200 Stations sorted by distance, with per-source provenance and warnings
- 400 Missing or invalid coordinates
GET /api/field
Regional wind grid (flow vectors in mph) for map particle layers.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required |
| lon | query | number | required |
| spanDeg | query | number | optional · 0.5…8, default 2 |
| cols | query | integer | optional · default 12 |
| rows | query | integer | optional · default 8 |
| time | query | string (date-time) | optional · Optional hour within the next 2 days |
curl \ "https://thewindagent.com/api/field?lat=52.3&lon=-7.6&spanDeg=2&cols=12&rows=8"
{ "bbox": { "west": -8.6, "south": 51.3, "east": -6.6, "north": 53.3 }, "cols": 12, "rows": 8,
"points": [ { "lat": 53.3, "lon": -8.6, "u": 2.1, "v": -1.4, "speedMph": 5.6 }, … ],
"stats": { "minMph": 3.2, "maxMph": 11.4 }, "provenance": { "source": "Open-Meteo" } }- 200 Row-major points from the north-west corner with u/v flow vectors and stats
- 400 Invalid parameters
POST /api/route
Headwind and crosswind analysis along a route, per segment and hour.
| Param | In | Type | Notes |
|---|---|---|---|
| points | body | array | required |
| hours | body | integer | optional · 1…48, default 24 |
| startTime | body | string (date-time) | optional |
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "points": [ { "lat": 52.35, "lon": -7.7 }, { "lat": 52.1, "lon": -7.1 } ], "hours": 12 }' \
"https://thewindagent.com/api/route"{ "segments": [ { "index": 0, "bearingDeg": 128, "distanceKm": 55.2, "hourly": [ { "time": "2026-10-03T16:00", "headwindMph": 3.1, "crosswindMph": 4.8 }, … ] } ],
"totals": { "distanceKm": 55.2, "byHour": [ … ], "bestDeparture": { "time": "2026-10-03T18:00", "meanHeadwindMph": -1.2, "reason": "Highest comfort score (88/100) …" } }, "provenance": { "source": "Open-Meteo 10 m" } }- 200 Segments, hourly relative wind, totals and best departure
- 400 Invalid body
GET /api/brief
Fetch a stored brief.
| Param | In | Type | Notes |
|---|---|---|---|
| id | query | string | required |
curl \ "https://thewindagent.com/api/brief?id=k3m5x7q2ab"
{ "brief": { "id": "k3m5x7q2ab", "place": { … }, "mode": "crane", "decision": { … }, "provenance": { … }, "createdAt": "2026-10-03T06:40:00Z" } }- 200 `{ brief }` (Cache-Control public, max-age=3600)
- 404 Not found
POST /api/brief
Store a shareable evidence brief (20/min/IP, 32 KB max).
| Param | In | Type | Notes |
|---|---|---|---|
| place | body | object | required |
| mode | body | golf | crane | spray | marine | drone | motorsport | events | required |
| hour | body | object | required |
| decision | body | object | required |
| extras | body | object | optional |
| provenance | body | object | required |
curl -X POST \
-H "Content-Type: application/json" \
-d '{ "place": { "name": "Cork Docks", "latitude": 51.9, "longitude": -8.4 }, "mode": "crane", "hour": { "time": "2026-10-03T16:00", "speedMph": 12.1 }, "decision": { "verdict": "WATCH", "summary": "…", "recommendation": "…", "threshold": "27 mph gust", "drivers": ["…"], "tone": "watch" }, "provenance": { "source": "Open-Meteo" } }' \
"https://thewindagent.com/api/brief"{ "id": "k3m5x7q2ab", "url": "https://thewindagent.com/b/k3m5x7q2ab" }- 201 Created
- 400 Invalid brief
- 413 Brief exceeds 32 KB
- 429 Rate limit reached
GET /api/meteogram
Stacked hourly meteogram with derived spray and stability fields.
One Open-Meteo forecast call (past_days=2) with 10 m wind and gust, direction, 80/120/180 m wind, temperature, humidity, dew point, surface and MSL pressure, precipitation, cloud, CAPE and boundary-layer height, plus daily sunrise/sunset and maxima. Derived per hour: Beaufort force, gust factor (null when mean < 2 mph), Delta T (dry bulb − Stull 2011 wet bulb, °C) and 3 h MSL pressure tendency. Times are naive site-local strings. Missing values are null. Cache-Control max-age=600.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| days | query | integer | optional · 7…16, default 16 |
curl \ "https://thewindagent.com/api/meteogram?lat=52.3389&lon=-7.6489&days=7"
{ "location": { … }, "nowHour": "2026-10-03T16:00",
"hours": [ { "time": "2026-10-03T16:00", "speedMph": 5.1, "gustMph": 11, "beaufort": 2, "gustFactor": 2.2, "deltaTC": 3.4, "pressureTendency3hHpa": -0.8, "boundaryLayerM": 640 }, … ],
"daily": [ { "date": "2026-10-03", "sunrise": "07:25", "sunset": "18:47", "maxGustMph": 18 }, … ], "coverage": { … }, "warnings": [], "provenance": { … } }- 200 { location, nowHour, hours[], daily[], coverage, derived, warnings, provenance }
- 400 Invalid parameters
- 502 Forecast source unavailable
GET /api/compare
Seven deterministic models side by side (10 m).
Per-model hourly 10 m speed, gust and direction for ECMWF IFS, DWD ICON, NOAA GFS, UK Met Office, Météo-France, ECCC GEM and JMA (models that return no data are listed in missingModels). Per hour: speed spread (max − min) and circular direction spread (models with ≥ 2 mph). No blending. Cache-Control max-age=900.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| days | query | integer | optional · 1…7, default 3 |
curl \ "https://thewindagent.com/api/compare?lat=52.3389&lon=-7.6489&days=3"
{ "models": [ { "id": "ecmwf_ifs025", "label": "ECMWF IFS", "resolutionKm": 25 }, … ],
"hours": [ { "time": "2026-10-03T16:00", "byModel": { "ecmwf_ifs025": { "speedMph": 5.0 }, "icon_seamless": { "speedMph": 5.6 } }, "modelCount": 7, "spreadMph": 2.4, "circularSpreadDeg": 14 }, … ],
"missingModels": [], "provenance": { … } }- 200 { models[{id,label,attribution,resolutionKm}], hours[{time, byModel, modelCount, spreadMph, circularSpreadDeg}], provenance }
- 400 Invalid parameters
- 502 Model comparison source unavailable
GET /api/history
What actually happened — ERA5 reanalysis plus recent analysis.
Hourly 10 m speed, gust, direction, temperature and MSL pressure for the last N days ending yesterday from ERA5 (Open-Meteo archive). ERA5 lags ~5 days; later hours are filled from forecast past_days short-range output and labelled source:"analysis" per hour. Cache-Control max-age=3600.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
| days | query | integer | optional · 7…30, default 14 |
curl \ "https://thewindagent.com/api/history?lat=52.3389&lon=-7.6489&days=14"
{ "window": { "from": "2026-09-19", "to": "2026-10-02" },
"hours": [ { "time": "2026-09-19T00:00", "speedMph": 8.2, "gustMph": 17.0, "directionDeg": 240, "temperatureC": 11.2, "pressureMslHpa": 1009.4, "source": "era5" }, … ],
"coverage": { … }, "warnings": [], "provenance": [ { "source": "ERA5 via Open-Meteo archive" } ] }- 200 { window, hours[{time,speedMph,gustMph,directionDeg,temperatureC,pressureMslHpa,source}], coverage, warnings, provenance[] }
- 400 Invalid parameters
- 502 Both history sources unavailable
GET /api/extremes
Gust return periods, top gust days and monthly climatology (ERA5 since 1990).
One ERA5 daily request from 1990-01-01 to the end of last year. Annual maxima of daily max 10 m gust (and max mean speed) → Gumbel MLE → return levels for 2/5/10/20/50 years with 90 % bootstrap CI (200 seeded resamples). Top-10 de-clustered gust days; stormFlag (Irish locations, gust > 60 mph, dates only). Monthly mean/p90 of daily means. Result cached in KV per 0.25° ERA5 cell for 30 days (`cache: hit|miss`). Cache-Control max-age=86400.
| Param | In | Type | Notes |
|---|---|---|---|
| lat | query | number | required · -90…90 |
| lon | query | number | required · -180…180 |
curl \ "https://thewindagent.com/api/extremes?lat=52.3389&lon=-7.6489"
{ "period": { "from": "1990-01-01", "to": "2025-12-31" },
"gust": { "returnLevels": [ { "years": 50, "mph": 71.4, "ci90": [66.0, 79.8] }, … ] },
"topGustDays": [ { "date": "2025-01-24", "gustMph": 74 }, … ], "monthly": [ … ], "method": "Gumbel MLE", "caveats": [ … ], "cache": "hit" }- 200 { period, annualMaxima[], gust{fit,returnLevels[],curve[]}, speed{...}, topGustDays[], monthly[], method, caveats[], provenance }
- 400 Invalid parameters
- 502 ERA5 archive unavailable
GET /api/ireland/live
Every live wind observation on the island of Ireland.
Concurrent fetch of Met Éireann open observations (25 stations, today's hourly rows; CC BY 4.0), METAR for the Ireland + Northern Ireland bbox (aviationweather.gov) and the Marine Institute Irish Weather Buoy Network via ERDDAP (last 24 h; NDBC 62081/62105 fallback). Per-source timeouts; partial failures become warnings. Speeds converted to mph. Cache-Control max-age=300.
No parameters.
curl \ "https://thewindagent.com/api/ireland/live"
{ "stations": [ { "id": "…", "name": "Malin Head", "source": "met-eireann", "latitude": 55.37, "longitude": -7.34, "speedMph": 21.0, "gustMph": 33.4, "directionDeg": 250, "ageMinutes": 12 }, … ],
"summary": { "count": 61, "strongestGust": { … }, "meanSpeedMph": 11.9 }, "provenance": [ … ], "warnings": [] }- 200 { stations[{id,name,source,latitude,longitude,speedMph,gustMph,directionDeg,observedAt,ageMinutes,pressureHpa?,waveHeightM?,wavePeriodS?,recent?}], summary{count,strongestGust,meanSpeedMph}, provenance[], warnings[] }
- 502 No observation source answered
GET /api/field/global
Global 10 m wind flow field (36x18 grid).
648-point global grid (lon -175..175 step 10, lat 85..-85 step 10, row-major from the north-west) of current 10 m wind from Open-Meteo, as flow vectors u/v and speed in m/s (null where missing). Cached 15 min in KV, served stale up to 2 h (stale:true) if upstream fails. `cache` is "hit" or "miss". Cache-Control max-age=300.
No parameters.
curl \ "https://thewindagent.com/api/field/global"
{ "cols": 36, "rows": 18, "lonStart": -175, "latStart": 85, "step": 10, "u": [ … 648 values ], "v": [ … ], "speed": [ … ], "updated": "2026-10-03T16:00:00Z", "cache": "hit" }- 200 { cols, rows, lonStart, latStart, step, u[648], v[648], speed[648], updated, provenance, cache, stale? }
- 502 Upstream unavailable and no usable cache
GET /api/counters
Live display counters for the landing page.
stationsReporting (Ireland live stations with age <= 90 min, 60 s cache), forecastsServedToday (sampled KV counter), recordsFrozen (briefs stored), contentUnits, counties, charts, industries. Unavailable counters are null. Cache-Control max-age=60.
No parameters.
curl \ "https://thewindagent.com/api/counters"
{ "stationsReporting": 58, "forecastsServedToday": 1840, "recordsFrozen": 322, "contentUnits": 900, "counties": 32, "charts": 30, "industries": 40, "updated": "2026-10-03T16:00:00Z" }- 200 { stationsReporting, forecastsServedToday, recordsFrozen, contentUnits, counties, charts, industries, updated }
Account endpoints (session or secret)
These act on a signed-in account, so they need the browser session cookie and a same-origin Origin header, and cannot be called with an API key. Examples use $WA_SESSION for the cookie value. /api/alerts/run is the scheduler's entry point and needs a server-side secret.
PATCH /api/sites
Update a saved site's name, rule, alerts or working height.
Session cookie + same-origin required. `null` removes rule/alerts/heightM.
| Param | In | Type | Notes |
|---|---|---|---|
| id | query | string (uuid) | required |
| name | body | string | optional |
| rule | body | any | optional |
| alerts | body | any | optional |
| heightM | body | number | null | optional · 1…500 |
curl -X PATCH \
-H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \
-H "Content-Type: application/json" \
-d '{ "rule": { "metric": "gust", "comparison": "gte", "thresholdMph": 27, "label": "Crane out of service", "sourceDocument": "Lift plan LP-14" }, "alerts": { "email": true, "leadHours": 24 }, "heightM": 45 }' \
"https://thewindagent.com/api/sites?id=3f0c9a52-…"{ "site": { "id": "3f0c9a52-…", "name": "Cork Docks", "heightM": 45, "rule": { "metric": "gust", "comparison": "gte", "thresholdMph": 27, … } } }- 200 Updated site
- 400 Invalid update
- 401 Sign in required
- 403 Cross-origin request rejected
- 404 Site not found
GET /api/alerts
Last 50 fired alerts for the signed-in user (or `?preview=<siteId>` to evaluate one site now).
| Param | In | Type | Notes |
|---|---|---|---|
| preview | query | string (uuid) | optional |
curl \ -H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \ "https://thewindagent.com/api/alerts"
{ "alerts": [ { "id": "…", "siteId": "…", "siteName": "Cork Docks", "rule": { … }, "firedAt": "2026-10-03T17:30:12Z", "delivery": "email", "unknownHours": 0, "link": "…", "evidence": { … }, "windows": [ { "start": "2026-10-04T03:00", "end": "2026-10-04T08:00", "hours": 5, "peakMph": 44, "peakTime": "2026-10-04T05:00" } ] } ] }- 200 `{ alerts: FiredAlert[] }` or `{ evaluation }`
- 401 Sign in required
POST /api/alerts/run
Scan every saved site and fire due alerts (also runs on the */30 cron trigger).
| Param | In | Type | Notes |
|---|---|---|---|
| X-Alert-Secret | header | string | required |
curl -X POST \ -H "X-Alert-Secret: $ALERT_RUN_SECRET" \ "https://thewindagent.com/api/alerts/run"
{ "scanned": 128, "fired": 3, "skipped": 120, "errors": 0 }- 200 Scan summary
- 403 Bad secret
- 503 ALERT_RUN_SECRET not configured
GET /api/keys
List the signed-in user's API keys (never returns the secret).
No parameters.
curl \ -H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \ "https://thewindagent.com/api/keys"
{ "keys": [ { "id": "…", "label": "Dashboard", "prefix": "wa_live_Ab3d", "createdAt": "2026-09-30T09:00:00Z", "lastUsedAt": null } ], "max": 5 }- 200 `{ keys, max }`
- 401 Sign in required
POST /api/keys
Create an API key (Pro/Ops/Enterprise, max 5). The key is returned once..
| Param | In | Type | Notes |
|---|---|---|---|
| label | body | string | optional |
curl -X POST \
-H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \
-H "Content-Type: application/json" \
-d '{ "label": "Dashboard" }' \
"https://thewindagent.com/api/keys"{ "key": "wa_live_…", "record": { "id": "…", "label": "Dashboard", "prefix": "wa_live_Ab3d" } }- 201 `{ key: wa_live_…, record }`
- 403 Plan does not include API access
- 409 Key limit reached
DELETE /api/keys
Revoke an API key.
| Param | In | Type | Notes |
|---|---|---|---|
| id | query | string (uuid) | required |
curl -X DELETE \ -H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \ "https://thewindagent.com/api/keys?id=3f0c9a52-…"
{ "revoked": true }- 200 Revoked
- 404 Not found
Rate limits
| Plan | Calls / UTC day | Keys |
|---|---|---|
| starter | — | No API access |
| pro | 1,000 | 5 |
| ops | 10,000 | 5 |
| enterprise | 100,000 | 5 |
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the cap you get 429 with Retry-After.
Errors
| 400 | Invalid coordinates, mode or thresholds |
| 401 | Missing, malformed or revoked key |
| 403 | Plan does not include API access |
| 429 | Daily cap reached |
| 502 | Forecast source unavailable — retry; we never return stale data as fresh |
Units and conventions
- Speed is miles per hour. mph is the internal unit everywhere. Convert at the edge: 1 mph = 1.609 km/h = 0.869 kt = 0.447 m/s.
- Direction is where the wind blows from, in degrees clockwise from north. 270 is a westerly.
- Heights are metres above ground. Model levels are 10, 80, 120 and 180 m; the 10 m values are the top-level fields and the others sit under heights.h80 / h120 / h180. Gust exists at 10 m only.
- Times are site-local wall clock without an offset, in location.timezone. Window ends are exclusive.
- null is never zero. A missing level or value is null, a field that could not be computed is absent or flagged, and an hour missing core fields is dropped and counted under provenance.coverage. Treat null as UNKNOWN.
- Probabilities are raw. pExceed is the fraction of ensemble members at or above a limit, uncalibrated, and null with insufficient: true under 10 members.
The decision packet
Every number the API returns is a computed value with provenance; the packet is the same shape the instrument and the agent use. current holds a tone (good, watch or stop), a verdict and score, a one-line summary, a recommendation, the threshold the verdict was judged against and the list of drivers. candidateWindows lists runs of hours inside your limits. provenance names the decision engine, the forecast source, the model runs and the coverage. The tone is a rule evaluation of the limits you passed, not a clearance, and nothing in the packet says a task is safe.
Versioning
/api/v1 is the stable surface. Within v1 we add fields and endpoints but do not rename, remove or change the meaning of existing ones; clients must ignore unknown fields. A breaking change ships under a new prefix with the old one kept running, and the OpenAPI document at the repository root is the source for this page. The instrument endpoints below it can change when the instrument does.
Attribution
Show “Wind data: The Wind Agent” with the upstream sources wherever you display values: Open-Meteo · ECMWF IFS/ENS · NOAA GFS/GEFS · DWD ICON · ERA5 (Copernicus) · aviationweather.gov METAR · NOAA NDBC · OpenFreeMap/OpenStreetMap. Open-Meteo data is CC BY 4.0. Label values as modelled forecasts — planning support, not on-site measurement — and never present them as a safety clearance.