magnus919_agent-skills/tempest/references/rest-api-and-auth.md

Tempest REST API and Authentication

The Tempest REST API is the cloud service at https://swd.weatherflow.com/swd/rest. It is the primary, recommended data source even for programs running on the same LAN as the hub; the local UDP broadcast (see udp-broadcast-protocol.md) is officially positioned as an off-grid backup. Base URL used throughout:

https://swd.weatherflow.com/swd/rest

Authentication: the personal access token

There are exactly two documented authentication methods, and the bundled CLI uses the first:

1. Personal Access Token — the right choice for scripts and integrations without a graphical interface. Sign in to the Tempest Web App (tempestwx.com), then go to Settings → Data Authorizations → Create Token, and copy the generated token. This is what TEMPEST_TOKEN carries.
2. OAuth 2.0 (Authorization Code, optionally with PKCE) — the documented choice for production apps with a web UI. Apps are registered from the account's Developers page; authorization and token endpoints are documented separately in the OAuth reference. The CLI does not implement OAuth.

On the wire, the token travels as a query parameter:

GET https://swd.weatherflow.com/swd/rest/stations?token=<YOUR_TOKEN>

The official quick-start examples use token=[your_access_token] and show no Authorization header alternative for this API. Do not send the token as a header or assume bearer syntax is supported. The OpenAPI document describes the scheme as apiKey with in: query, which matches.

Policy notes (remote-developer-policy): personal-use access covers station metadata, observations, and forecasts with "rate/volume limits (enough for personal use)". No numeric quota is published, and no 429 response behavior is documented. Higher-volume or network-wide access requires a commercial agreement (TempestONE). Keep personal integrations to your own stations.

Endpoint catalog (personal-use surface)

GET /stations — your stations with devices

Parameters: limit (int64, default 10000), next_cursor (string; present when more than 10,000 stations are provisioned), optional geographic filters (lat_min/lon_min/lat_max/lon_max bounding box, or center_lat/center_lon/radius in meters).

Response is a StationSet wrapper, not a bare list:

{
  "status": { "status_code": 0, "status_message": "SUCCESS" },
  "stations": [
    {
      "station_id": 12799,
      "location_id": 12799,
      "name": "Home",
      "public_name": "Home",
      "latitude": 42.37,
      "longitude": -71.06,
      "timezone": "America/New_York",
      "timezone_offset_minutes": -300,
      "station_meta": { "elevation": 1567.65, "share_with_wf": true, "share_with_wu": true },
      "is_local_mode": false,
      "devices": [
        {
          "device_id": 60526,
          "serial_number": "ST-00012345",
          "device_type": "ST",
          "hardware_revision": "3",
          "firmware_revision": "165",
          "device_meta": { "agl": 2.2, "name": "Backyard", "environment": "outdoor" },
          "device_settings": { "show_precip_final": false },
          "notes": ""
        }
      ],
      "station_items": [ { "item": "air_temperature_humidity", "device_id": 60526, "sort": 0 } ]
    }
  ]
}

device_type values: HB (hub — has no observation data), ST (Tempest all-in-one), AR (Air sensor), SK (Sky sensor). The OpenAPI enum lists exactly these four. Note that AR/SK are metadata codes for the Air/Sky hardware; the observation type discriminator for the same hardware is obs_air/obs_sky. Always filter HB out before auto-selecting a device for observation calls — the hub has no /observations/device/{id} data. A null or missing serial_number on a device means inactive hardware per the legacy docs.

GET /stations/{station_id} — one station

Same Station model; documented responses are 200 and 404 ("Station not found"). Per the legacy Swagger the body still arrives in the {stations: [...]}-style wrapper shape with the selected station inside, so unwrap defensively rather than assuming a bare station object.

GET /observations/device/{device_id} — device observations

Query parameters (mutually exclusive modes):

Parameter	Meaning
day_offset	Whole UTC day: 0 = current UTC day, 1 = yesterday UTC
time_start + time_end	UTC epoch-seconds range; one-minute resolution guaranteed for ranges ≤ 5 days
latest=true	Latest single observation (the CLI's current default)
format=csv	CSV instead of JSON

Response is an observation set: obs (array of positional arrays, oldest to newest), type (obs_st | obs_air | obs_sky — the layout discriminator), plus device identity/status fields. Field layouts are in observation-layouts.md. Documented errors: 404 "Device not found". Passing a hub HB device id yields no observation data.

GET /observations/stn/{station_id} — station observations

Note the segment is stn, not stations. Optional parameters: time_start/time_end, bucket (1 | 5 | 30 | 180 minutes; mapped to 1 day / 5 days / 30 days / 180 days of history, and the docs mention 1440 ≈ 4 years), ob_fields selection, and the standard unit parameters. Station observations are federated from the station's designated primary sensors; device observations are one physical device's raw data. Use station observations when you want "the station's" reading, device observations when you care about a specific unit.

GET /better_forecast — conditions + daily + hourly

Parameters: station_id (or lat/lon with optional snap_to_nearest_owned_station=true for within-5 km snapping), plus unit overrides: units_temp (c|f), units_wind (mph|kph|kts|mps|bft| lfm), units_pressure (mb|inhg|mmhg|hpa), units_precip (mm|cm|in), units_distance (km|mi).

Response top level:

{
  "status": { "status_code": 0, "status_message": "SUCCESS" },
  "current_conditions": { "air_temperature": 18.2, "conditions": "Mostly Clear", "icon": "partly-cloudy-day", "relative_humidity": 61, "station_pressure": 1015.4, "wind_avg": 2.1, "wind_direction": 225, "feels_like": 18.2 },
  "forecast": {
    "daily": [ { "day_start_local": 1778385600, "air_temp_high": 25.4, "air_temp_low": 15.1, "conditions": "Partly cloudy", "precip_probability": 10, "precip_type": "rain", "sunrise": 1778378400, "sunset": 1778425200 } ],
    "hourly": [ { "time": 1778388000, "local_hour": 10, "local_day": 10, "air_temperature": 19.8, "precip_probability": 5, "conditions": "Sunny" } ]
  },
  "units": { "units_temp": "c", "units_wind": "mps", "units_precip": "mm", "units_pressure": "mb", "units_distance": "km" },
  "latitude": 42.37, "longitude": -71.06,
  "timezone": "America/New_York", "timezone_offset_minutes": -300
}

The critical structural fact: daily and hourly live under the forecast wrapper key, not at top level. Reading data["daily"] returns nothing.

Unit behavior: the response honors the requested units and reports what it used in units. Default is Celsius/m/s/mm/mb, but the endpoint is unit-selectable — not Celsius-locked. units_temp=f is documented and honored. Any consumer that hard-codes Celsius conversion must first read units.units_temp, or it will double-convert Fahrenheit responses (see units-and-conversions.md).

Timestamps: day_start_local, sunrise, sunset, and hourly time are integer epoch seconds. Hourly objects carry local_hour (int 0–23) and local_day (int day-of-month); there is no local_time or time_string field — code expecting one silently falls back to its default branch.

Other documented endpoints

• GET /diagnostics/{station_id} — latest station status; 200/401/404.
• GET /stats/station/{station_id} — daily/weekly/monthly/annual/all-time high-low-average statistics; 200/401.
• GET /metadata/network/stations and GET /observations/network/stations — network-wide access governed by the remote data policy (not part of the personal single-station flow).
• Lightning endpoints exist but documented access is for paid subscribers.
• The current docs index does not document /user/devices for the consumer surface — use /stations and its nested devices array. There is no /better_forecast/hourly route; hourly data is forecast.hourly inside the standard /better_forecast response.

Error signatures

Status	Documented meaning	Practical symptom
401	Unauthorized (documented on forecast/diagnostics/stats)	Missing, revoked, or mistyped token — regenerate at tempestwx.com Settings → Data Authorizations
403	Not documented for this API	Treat as access-denied to that station/device; verify the token belongs to the station owner
404	"Station not found" / "Device not found" (documented)	Wrong station/device id, or an HB hub id passed to an observation endpoint

No JSON error-body schema is published, so parse defensively. No numeric rate limit or 429 behavior is documented; the policy only promises personal-use volume is acceptable. The CLI maps 401/403/404 to targeted messages and dumps the response body for anything else.

Worked recipes

Recipe A: stations → pick sensor → latest observation

# 1. List stations (StationSet wrapper)
curl -s "https://swd.weatherflow.com/swd/rest/stations?token=$TEMPEST_TOKEN"
# 2. Choose a device: devices[].device_type must not be "HB"; prefer ST
# 3. Latest observation for that device
curl -s "https://swd.weatherflow.com/swd/rest/observations/device/$DEVICE_ID?token=$TEMPEST_TOKEN"

The observation response's type field selects the positional layout (obs_st: temperature is index 7, epoch is index 0). One command does all three steps: tempest current --json.

Recipe B: station forecast with explicit units

curl -s "https://swd.weatherflow.com/swd/rest/better_forecast?station_id=$STATION_ID&units_temp=c&units_wind=mps&units_pressure=mb&units_precip=mm&token=$TEMPEST_TOKEN" \
  | jq '{current: .current_conditions.air_temperature,
         days: [.forecast.daily[] | {day_start_local, air_temp_high, air_temp_low}],
         units: .units.units_temp}'

Read units instead of assuming units. Extract daily/hourly from .forecast.daily / .forecast.hourly.

Recipe C: a UTC day of device history

# day_offset=1 is yesterday UTC; day_offset=0 is today
curl -s "https://swd.weatherflow.com/swd/rest/observations/device/$DEVICE_ID?day_offset=1&token=$TEMPEST_TOKEN" \
  | jq '{type, count: (.obs | length), first: .obs[0], last: .obs[-1]}'

For a custom range, send both time_start and time_end as epoch seconds and keep the span ≤ 5 days to guarantee one-minute resolution. Do not mix day_offset with time_start/time_end in one call.

Sources

• https://apidocs.tempestwx.com/reference/quick-start (auth flows, REST examples, primary-source guidance)
• https://apidocs.tempestwx.com/reference/oauth (OAuth 2.0 grant types, app registration)
• https://apidocs.tempestwx.com/reference/get_stations (StationSet/Station/Device OpenAPI schemas)
• https://apidocs.tempestwx.com/reference/getstationbyid-1 (single station, 404 semantics)
• https://apidocs.tempestwx.com/reference/getobservationsbydeviceid (device observation parameters, 404)
• https://apidocs.tempestwx.com/reference/get_observations-stn-station-id (station observations, bucket)
• https://apidocs.tempestwx.com/reference/station-vs-device (device vs station observation semantics)
• https://apidocs.tempestwx.com/reference/get_better-forecast-1 (forecast parameters, unit selection)
• https://apidocs.tempestwx.com/reference/get_diagnostics-station-id-1 (diagnostics endpoint)
• https://apidocs.tempestwx.com/reference/get_stats-station-station-id-1 (stats endpoint)
• https://apidocs.tempestwx.com/reference/observation-record-format (type discriminators, record lengths)
• https://apidocs.tempestwx.com/reference/tempest-udp-broadcast (UDP as backup to REST)
• https://weatherflow.github.io/Tempest/api/swagger/ (legacy response models: forecast nesting, obs_sky null day-rain)
• https://weatherflow.github.io/Tempest/api/remote-developer-policy.html (personal-use policy, rate/volume limits)