Reference

API Reference

Base URL https://api.theweatheragent.com. All responses are JSON. Every response that carries relayed data includes an attribution string and a disclaimer field.

Data disclaimer. WeatherAgent relays and normalizes data from third-party upstream providers (including NOAA, ECMWF, DWD, Météo-France, MET Norway and Copernicus Marine). Data is provided "as is", without warranty of any kind, and may be delayed, incomplete or inaccurate. It is not a substitute for official marine forecasts, notices to mariners, or your own judgment. Independently verify all data against official sources before acting on it — especially any decision affecting personal safety or navigation. Data is relayed from upstream sources and must be independently verified — it is not the sole basis for decisions affecting safety of life or property at sea.

Authentication

Send your API key in the X-API-Key header (an Authorization: Bearer <key> header also works). Keys are issued once, at email verification, and stored only as a hash — we cannot recover a lost key, but you can issue another.

X-API-Key: wa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quota is counted per account, not per key. Holding several keys does not grant additional allowance.

What counts as a call

Outcome	Counts as
`200` from a data endpoint	1 call
Cache hit (same request inside the same model cycle)	0 calls
`4xx` / `429`	0 calls

Free tier is 10 calls/day per account, resetting at 00:00 UTC. Exceeding it returns 429 with a machine-readable quota object and a Retry-After header.

MCP server — free

Connect your own AI agent over the Model Context Protocol at no cost. The MCP server is free to use and needs no separate plan or signup beyond an API key. Data calls it makes count toward your normal API allowance — the same per-account daily quota as REST. Metadata lookups do not.

Tool	What it does	Counts toward quota
`get_point_forecast`	Marine/weather point with a value per source	Yes — 1 call
`get_tide_extremes`	Tide highs/lows for a day	Yes — 1 call when available
`generate_fishing_report`	Report built from relayed data	Yes — base + 1 per ladder leg
`list_sources`	Source catalog and licences	No — metadata
`get_usage`	Quota readout	No — metadata
`get_disclaimer`	The disclaimer, attribution and plan table	No — metadata

# stdio WEATHERAGENT_API_KEY=*** npx weatheragent-mcp --transport stdio # HTTP / SSE (server) WEATHERAGENT_API_KEY=*** \ WEATHERAGENT_MCP_TRANSPORT=http \ WEATHERAGENT_MCP_PORT=8790 \ npx weatheragent-mcp

Auth is required. Free does not mean anonymous — the server needs your API key so data calls are attributed to your account and quota can be enforced. There is no separate MCP price and no MCP-only upsell.

Ladder legs stay a paid feature via MCP exactly as over REST. The plan is read from your account, not from the MCP server's configuration, so it cannot be self-granted locally.

Agents do not read our docs. Because any third-party agent may consume this server, the disclaimer is a mandatory field in every data-bearing tool response rather than free prose — it is structurally impossible to return relayed data without it. Data is relayed from upstream sources and must be independently verified; it is not the sole basis for decisions affecting safety of life or property at sea.

Endpoints

GET/healthNo auth

Liveness and configuration readout. Useful for status pages and uptime checks.

curl https://api.theweatheragent.com/health

{ "ok": true, "service": "weatheragent-api", "version": "0.1.0-p0", "sources_enabled": ["ndbc", "nws"], "auth_mode": "off", "cache_bound": true, "db_bound": true, "time": "2026-09-12T01:00:20.871Z" }

Status	Meaning
`200`	Service up. Inspect `cache_bound` / `db_bound` for dependency health.

GET/v2/marine/pointAuth

Marine and weather values at a coordinate, returned as one value per source per timestamp plus a spread/agreement statistic. Sources are never averaged into a single number.

lat required: Latitude in [-90, 90].
lng required: Longitude in [-180, 180].
params: Comma-separated. Defaults to waveHeight,wavePeriod,windSpeed. Unknown ids are rejected with 400, never silently dropped.
hours: Forecast window, 1–240. Default 48.
units: metric (default) or imperial.

Available params: waveHeight, wavePeriod, waveDirection, swellHeight, swellPeriod, swellDirection, windSpeed, windDirection, windGust, airTemperature, waterTemperature, pressure, currentSpeed, currentDirection, visibility, precipitation, cloudCover.

curl "https://api.theweatheragent.com/v2/marine/point?lat=27.97&lng=-83.36&params=waveHeight,windSpeed&hours=6" \ -H "X-API-Key: wa_live_..."

{ "request": { "lat": 27.97, "lng": -83.36, "params": ["waveHeight","windSpeed"], "hours": 6, "units": "metric" }, "hours": [ { "time": "2026-09-11T23:00:00.000Z", "waveHeight": { "ndbc": 0.4 }, "windSpeed": { "nws": 2.572 } } ], "meta": { "sources_ok": ["ndbc","nws"], "sources_failed": [], "cache": "miss", "stale": false, "freshness": { "newest_valid": "2026-09-19T05:00:00.000Z", "horizon_hours": 172, "newest_observation": "2026-09-12T00:00:00.000Z", "observation_age_minutes": 61 }, "spread": { "waveHeight": { "min":0.4,"max":0.4,"median":0.4,"agree":1,"n":1 } }, "units": "metric", "attribution": "...", "disclaimer": "..." } }

Status	Meaning
`200`	Data returned. Check `meta.sources_ok` / `sources_failed` and `meta.stale`.
`400`	Bad `lat`, `lng`, `hours`, `units`, or an unknown `params` id.
`401`	Missing or invalid API key.
`422`	No enabled source can serve the requested parameters.
`429`	Daily quota exhausted. See the 429 contract below.
`502`	Every resolved source failed. No partial or invented value is returned.

Reading the data: spread.agree counts the sources inside an agreement band of max(param band, 10% of the median). A forecast's newest_valid is in the future by design — use newest_observation for how current the observations are. Model resolution is ~0.25° (≈17 mi) for the gridded wave models, so a short ladder delta may sit inside a single cell; read it as a trend and trust the spread across sources over any single model's point value.

GET/v2/tide/extremes/pointAuth

Planned (P1). High/low tide times and heights for a day, relative to MSL, units stated. Documented here so the surface is known; the MCP tide tool reports it as not-yet-available rather than inventing data.

GET/v2/sourcesNo auth

The source catalog: id, dataset, resolution, cadence, area, licence, whether commercial use is permitted, and whether attribution is required. Use this to render correct attribution.

{ "sources": [ { "id": "ndbc", "name": "NOAA NDBC", "transport": "obs", "licence": "US Government work — public domain", "commercial_ok": true, "attribution_required": false }, { "id": "nws", "name": "NOAA / National Weather Service", "transport": "relay", "licence": "US Government work — public domain" } ], "note": "Every response carries one value per source per timestamp..." }

UK Met Office is deliberately excluded: its global wave product is CC-BY-SA (share-alike), which is incompatible with our terms through MVP.

GET/v2/disclaimerNo auth

Returns the current disclaimer and attribution strings. If you cache or re-serve our data, fetch these and attach them — they change when the source set changes.

{ "disclaimer": "WeatherAgent relays and normalizes data from third-party upstream providers...", "attribution": "Contains data from NOAA (public domain), ECMWF (CC BY 4.0)..." }

POST/v2/auth/signupNo auth

Create an account and send an email verification link. The free tier is gated on a verified address. Request JSON: { "email": "[email protected]", "device_fp": "optional" }.

curl -X POST https://api.theweatheragent.com/v2/auth/signup \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]"}'

HTTP/2 202 { "status": "verification_sent", "message": "Check your email to activate your API key.", "account_id": "...", "plan": "free" }

Status	Meaning
`202`	Verification email sent (or re-sent).
`400`	Missing or invalid email address.
`409`	That address already has a verified account.
`429`	Too many new accounts created from this connection recently.
`503`	Accounts store unavailable.

Note: outbound email delivery is deferred, so verification currently runs on a log transport and the response includes a dev_verify_url. That field disappears once a real mail provider is configured.

GET/v2/auth/verifyNo auth

Consume a verification token and issue an API key. Tokens are single-use and expire after 24 hours (the optional query parameters token and web are accepted; web=1 renders a short HTML confirmation page instead of JSON).

curl "https://api.theweatheragent.com/v2/auth/verify?token=..."

{ "api_key": "wa_live_...", "key_prefix": "wa_live_fd452a", "warning": "Store this key now. It is shown once and stored only as a hash.", "account": { "id": "...", "email": "[email protected]", "plan": "free" }, "quota": { "limit": 10, "resets_at": "2026-09-13T00:00:00.000Z", "basis": "per_account" } }

Status	Meaning
`200`	Verified; key issued. This is the only time the key is shown.
`400`	`token` missing, `invalid_token`, `token_expired`, or `token_already_used`.

GET/v2/usageAuth (optional)

Quota readout: used, limit, resets_at, plan, plus the definition of what counts as a call.

{ "quota": { "used": 3, "limit": 10, "resets_at": "2026-09-13T00:00:00.000Z", "plan": "free" }, "counts_as": { "ok_200": 1, "cache_hit": 0, "error_4xx": 0, "report_base": 1, "report_ladder_leg": 1 } }

GETPOST/v2/keysAuth

List your keys, or issue an additional one. A key's secret is returned only at creation.

GET /v2/keys → { "keys": [ { "key_prefix": "wa_live_fd452a", "scopes": "data,report,mcp", "revoked_at": null } ] } POST /v2/keys → { "api_key": "wa_live_...", "warning": "Store this key now..." }

Status	Meaning
`401`	Missing or invalid API key.

Quota is per account: additional keys do not add allowance.

DELETE/v2/keys/:idAuth

Revoke a key. Revocation is immediate and the key stops resolving on the next request.

Status	Meaning
`200`	Revoked.
`401`	Missing or invalid API key.
`404`	No such active key on your account.

The 429 contract

Quota exhaustion is machine-readable. The body carries a quota object and the response carries a Retry-After header in seconds.

HTTP/2 429 Retry-After: 83000 { "error": "quota_exceeded", "message": "Daily quota exhausted (10/10). Quota is per account and resets at 00:00 UTC. A cache hit does not consume quota.", "quota": { "used": 10, "limit": 10, "resets_at": "...", "plan": "free" }, "request_id": "..." }

Reports and metering

A fishing report is metered per leg: the base report is 1 call, tide adds 1, and each ladder leg you request adds 1. Ladder legs are optional and user-specified, so a report's total depends on what you ask for — there is no fixed report cost. Ladder legs require a paid plan.

Errors

Shape	Notes
`{ "error": "...", "message": "...", "request_id": "..." }`	Errors also carry `attribution` and `disclaimer`.
`404`	Body echoes the method actually received, e.g. `No route for GET /v2/auth/signup`. A wrong-method request reports the method Hono saw, which is the fastest way to diagnose a probe that sent the wrong verb.

Attribution. Contains data from NOAA (public domain), ECMWF (CC BY 4.0), DWD (GeoNutzV), Météo-France (Licence Ouverte 2.0), MET Norway (NLOD 2.0) and Copernicus Marine (E.U. Copernicus). Provided by WeatherAgent.

Disclaimer. WeatherAgent relays and normalizes data from third-party upstream providers. Data is provided "as is", without warranty of any kind, and may be delayed, incomplete or inaccurate. It is not a substitute for official marine forecasts, notices to mariners, or your own judgment. Independently verify all data against official sources before acting on it — especially any decision affecting personal safety or navigation.

© 2026 WeatherAgent