Weather watches tools
Watch National Weather Service alerts for the areas you serve and emit an event to an audience when a matching alert is issued.
create_weather_watch
Create a weather watch: a built-in event source that polls the National Weather Service every 10 minutes and, when a qualifying alert covers the territory, emits `emit_event_name` to the targeted audience's eligible contacts (active, not suppressed; bulk, idempotent, 72h default cooldown, permanent per-alert dedup). Optional hail, wind, and damage thresholds use OR semantics: any configured gate may qualify an alert. An audience is REQUIRED (audience_key XOR audience_id) — a watch is inherently geographic, so emitting to the whole roster must be the explicit choice audience_key: 'everyone'. Sequences listen via trigger event:<emit_event_name>. Territory: pass zone_codes (NWS UGC), lat/lng, or a plain location string. nws_event_types are EXACT names from the official NWS list (e.g. 'Flash Flood Warning'). Keep each alert type in exactly ONE watch per team unless you intend one storm to fire multiple events (the response includes a warning on overlap).
namestringrequiredemit_event_namestringrequired- Event sequences listen for, e.g. 'flood'.
nws_event_typesstring[]requiredzone_codesstring[]latnumberlngnumberlocationstring- Plain location, e.g. 'Richmond, VA' — resolved to NWS zones.
cooldown_hoursnumbermin_hail_inchesnumber | null- Optional minimum NWS maxHailSize in inches; null disables this gate.
min_wind_gust_mphnumber | null- Optional minimum NWS maxWindGust in mph; null disables this gate.
min_damage_threatenum | null- CONSIDERABLE | DESTRUCTIVE
Optional minimum NWS thunderstormDamageThreat; null disables this gate. audience_keystring- REQUIRED (this XOR audience_id): emission audience by slug, or the literal 'everyone'.
audience_idstring- REQUIRED (this XOR audience_key): emission audience by uuid.
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
list_weather_watches
List the team's weather watches (event types, territory, cooldown, status, last fired). Each row carries its emission `audience` ({id, name, kind, member_count}; kind 'default' = everyone).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
update_weather_watch
Update a weather watch: pause/resume (status), cooldown_hours, nws_event_types, optional hail/wind/damage thresholds (OR semantics), territory (zone_codes | lat/lng | location), or its emission audience (audience_key XOR audience_id; null resets to everyone). An audience rebind is FUTURE-ONLY — an alert already claimed keeps the audience snapshot it fired with.
watch_idstringrequirednamestringstatusenum- active | paused
emit_event_namestring- Retarget which event this watch emits.
cooldown_hoursnumbermin_hail_inchesnumber | null- Minimum NWS maxHailSize in inches; null clears this gate.
min_wind_gust_mphnumber | null- Minimum NWS maxWindGust in mph; null clears this gate.
min_damage_threatenum | null- CONSIDERABLE | DESTRUCTIVE
Minimum NWS thunderstormDamageThreat; null clears this gate. nws_event_typesstring[]zone_codesstring[]latnumberlngnumberlocationstringaudience_keystring | null- Rebind the emission audience by slug/'everyone' (XOR with audience_id; null resets to everyone).
audience_idstring | null- Rebind the emission audience by uuid (XOR with audience_key; null resets).
teamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
delete_weather_watch
Delete a weather watch (its firing history and alert-dedup log cascade). Sequences bound to its event stay — they just stop receiving it.
watch_idstringrequiredteamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.
fire_weather_watch
Manually fire a weather watch NOW ('storm is hitting early'). dry_run:true returns the eligible-contact count without sending (no idempotency_key needed). A REAL fire requires idempotency_key; retrying with the same key returns 200 with already_fired:true (safe no-op) — the 422s are for a missing idempotency_key on a real fire and for an active cooldown without force. Respects the cooldown unless force:true.
watch_idstringrequiredidempotency_keystring- Required for real fires; omit for dry_run.
dry_runbooleanforcebooleanteamstringrequired- Brand/team to act on (slug or id) → X-Cadence-Team. Required — your account key authorizes every brand you own, so this picks which one.