DEVELOPER REFERENCE · v1

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.

ParamTypeNotes
latnumber−90 … 90, required
lonnumber−180 … 180, required
curl -H "Authorization: Bearer wa_live_YOUR_KEY" \
  "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"
RESPONSE EXCERPT
{
  "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.

ParamTypeNotes
lat, lonnumberrequired
modeenumgolf · crane · spray · marine · drone · motorsport · events (required)
maxGustMphnumberdefault 25 — set it from your own document
minWindMphnumberdefault 3
maxWindMphnumberdefault 10
bearingDegnumber0 … 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"
DECISION PACKET SHAPE
{
  "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).

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
curl \
  -H "Authorization: Bearer wa_live_YOUR_KEY" \
  "https://thewindagent.com/api/v1/wind?lat=52.3389&lon=-7.6489"
EXAMPLE RESPONSE (TRIMMED)
{
  "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 } }
}
STATUS CODES

GET /api/v1/decision

Deterministic decision for now plus candidate windows (public API, bearer key).

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
modequerygolf | crane | spray | marine | drone | motorsport | eventsrequired
maxGustMphquerynumberoptional · default 25
minWindMphquerynumberoptional · default 3
maxWindMphquerynumberoptional · default 10
bearingDegquerynumberoptional · 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"
EXAMPLE RESPONSE (TRIMMED)
{
  "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)" }
}
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
daysqueryintegeroptional · 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"
EXAMPLE RESPONSE (TRIMMED)
{
  "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 } }
}
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
metricquerygust | speedoptional · default gust
heightqueryintegeroptional · default 10 · Metres above ground. gust supports 10 only; speed supports 10, 80, 100, 120 where the upstream has member data.
limitquerynumberoptional · 0… · Threshold in mph for pExceed / pExceedByModel.
daysqueryintegeroptional · 1…7, default 3
curl \
  "https://thewindagent.com/api/ensemble?lat=52.3389&lon=-7.6489&metric=speed&height=80&limit=20&days=2"
EXAMPLE RESPONSE (TRIMMED)
{
  "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." }
}
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
datequerystring (date)optional
forecastGustMphquerynumberoptional
forecastSpeedMphquerynumberoptional
curl \
  "https://thewindagent.com/api/climate?lat=52.3389&lon=-7.6489&date=2026-10-03"
EXAMPLE RESPONSE (TRIMMED)
{
  "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" }
}
STATUS CODES

GET /api/geocode

Find places.

ParamInTypeNotes
qquerystringrequired
curl \
  "https://thewindagent.com/api/geocode?q=Clonmel"
EXAMPLE RESPONSE (TRIMMED)
{ "results": [ { "name": "Clonmel", "area": "County Tipperary", "country": "Ireland", "latitude": 52.3555, "longitude": -7.7033 }, … ] }
STATUS CODES

POST /api/agent

Explain a deterministic wind decision.

The agent may explain supplied facts but does not create the verdict.

ParamInTypeNotes
questionbodystringrequired
modebodygolf | crane | spray | marine | drone | motorsport | eventsrequired
placebodyobjectrequired
windbodyanyrequired
decisionbodyobjectrequired
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"
EXAMPLE RESPONSE (TRIMMED)
{ "reply": "Gusts reach 24 mph at 15:00 against your 27 mph limit …", "provider": "grok", "engine": "grok", "unverified": [] }
STATUS CODES

GET /api/observations

Measured wind from nearby METAR stations and NDBC buoys (nearest 8).

ParamInTypeNotes
latquerynumberrequired
lonquerynumberrequired
radiusKmquerynumberoptional · 25…400, default 150
curl \
  "https://thewindagent.com/api/observations?lat=52.3389&lon=-7.6489&radiusKm=150"
EXAMPLE RESPONSE (TRIMMED)
{
  "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": []
}
STATUS CODES

GET /api/field

Regional wind grid (flow vectors in mph) for map particle layers.

ParamInTypeNotes
latquerynumberrequired
lonquerynumberrequired
spanDegquerynumberoptional · 0.5…8, default 2
colsqueryintegeroptional · default 12
rowsqueryintegeroptional · default 8
timequerystring (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"
EXAMPLE RESPONSE (TRIMMED)
{ "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" } }
STATUS CODES

POST /api/route

Headwind and crosswind analysis along a route, per segment and hour.

ParamInTypeNotes
pointsbodyarrayrequired
hoursbodyintegeroptional · 1…48, default 24
startTimebodystring (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"
EXAMPLE RESPONSE (TRIMMED)
{ "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" } }
STATUS CODES

GET /api/brief

Fetch a stored brief.

ParamInTypeNotes
idquerystringrequired
curl \
  "https://thewindagent.com/api/brief?id=k3m5x7q2ab"
EXAMPLE RESPONSE (TRIMMED)
{ "brief": { "id": "k3m5x7q2ab", "place": { … }, "mode": "crane", "decision": { … }, "provenance": { … }, "createdAt": "2026-10-03T06:40:00Z" } }
STATUS CODES

POST /api/brief

Store a shareable evidence brief (20/min/IP, 32 KB max).

ParamInTypeNotes
placebodyobjectrequired
modebodygolf | crane | spray | marine | drone | motorsport | eventsrequired
hourbodyobjectrequired
decisionbodyobjectrequired
extrasbodyobjectoptional
provenancebodyobjectrequired
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"
EXAMPLE RESPONSE (TRIMMED)
{ "id": "k3m5x7q2ab", "url": "https://thewindagent.com/b/k3m5x7q2ab" }
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
daysqueryintegeroptional · 7…16, default 16
curl \
  "https://thewindagent.com/api/meteogram?lat=52.3389&lon=-7.6489&days=7"
EXAMPLE RESPONSE (TRIMMED)
{ "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": { … } }
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
daysqueryintegeroptional · 1…7, default 3
curl \
  "https://thewindagent.com/api/compare?lat=52.3389&lon=-7.6489&days=3"
EXAMPLE RESPONSE (TRIMMED)
{ "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": { … } }
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
daysqueryintegeroptional · 7…30, default 14
curl \
  "https://thewindagent.com/api/history?lat=52.3389&lon=-7.6489&days=14"
EXAMPLE RESPONSE (TRIMMED)
{ "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" } ] }
STATUS CODES

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.

ParamInTypeNotes
latquerynumberrequired · -90…90
lonquerynumberrequired · -180…180
curl \
  "https://thewindagent.com/api/extremes?lat=52.3389&lon=-7.6489"
EXAMPLE RESPONSE (TRIMMED)
{ "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" }
STATUS CODES

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"
EXAMPLE RESPONSE (TRIMMED)
{ "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": [] }
STATUS CODES

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"
EXAMPLE RESPONSE (TRIMMED)
{ "cols": 36, "rows": 18, "lonStart": -175, "latStart": 85, "step": 10, "u": [ … 648 values ], "v": [ … ], "speed": [ … ], "updated": "2026-10-03T16:00:00Z", "cache": "hit" }
STATUS CODES

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"
EXAMPLE RESPONSE (TRIMMED)
{ "stationsReporting": 58, "forecastsServedToday": 1840, "recordsFrozen": 322, "contentUnits": 900, "counties": 32, "charts": 30, "industries": 40, "updated": "2026-10-03T16:00:00Z" }
STATUS CODES

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.

ParamInTypeNotes
idquerystring (uuid)required
namebodystringoptional
rulebodyanyoptional
alertsbodyanyoptional
heightMbodynumber | nulloptional · 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-…"
EXAMPLE RESPONSE (TRIMMED)
{ "site": { "id": "3f0c9a52-…", "name": "Cork Docks", "heightM": 45, "rule": { "metric": "gust", "comparison": "gte", "thresholdMph": 27, … } } }
STATUS CODES

GET /api/alerts

Last 50 fired alerts for the signed-in user (or `?preview=<siteId>` to evaluate one site now).

ParamInTypeNotes
previewquerystring (uuid)optional
curl \
  -H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \
  "https://thewindagent.com/api/alerts"
EXAMPLE RESPONSE (TRIMMED)
{ "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" } ] } ] }
STATUS CODES

POST /api/alerts/run

Scan every saved site and fire due alerts (also runs on the */30 cron trigger).

ParamInTypeNotes
X-Alert-Secretheaderstringrequired
curl -X POST \
  -H "X-Alert-Secret: $ALERT_RUN_SECRET" \
  "https://thewindagent.com/api/alerts/run"
EXAMPLE RESPONSE (TRIMMED)
{ "scanned": 128, "fired": 3, "skipped": 120, "errors": 0 }
STATUS CODES

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"
EXAMPLE RESPONSE (TRIMMED)
{ "keys": [ { "id": "…", "label": "Dashboard", "prefix": "wa_live_Ab3d", "createdAt": "2026-09-30T09:00:00Z", "lastUsedAt": null } ], "max": 5 }
STATUS CODES

POST /api/keys

Create an API key (Pro/Ops/Enterprise, max 5). The key is returned once..

ParamInTypeNotes
labelbodystringoptional
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"
EXAMPLE RESPONSE (TRIMMED)
{ "key": "wa_live_…", "record": { "id": "…", "label": "Dashboard", "prefix": "wa_live_Ab3d" } }
STATUS CODES

DELETE /api/keys

Revoke an API key.

ParamInTypeNotes
idquerystring (uuid)required
curl -X DELETE \
  -H "Cookie: $WA_SESSION" -H "Origin: https://thewindagent.com" \
  "https://thewindagent.com/api/keys?id=3f0c9a52-…"
EXAMPLE RESPONSE (TRIMMED)
{ "revoked": true }
STATUS CODES

Rate limits

PlanCalls / UTC dayKeys
starter—No API access
pro1,0005
ops10,0005
enterprise100,0005

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the cap you get 429 with Retry-After.

Errors

400Invalid coordinates, mode or thresholds
401Missing, malformed or revoked key
403Plan does not include API access
429Daily cap reached
502Forecast source unavailable — retry; we never return stale data as fresh

Units and conventions

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.

Get a keyPlans