---
title: "Create a storm monitor: email and/or webhook alerts when a qualifying storm enters an area"
method: POST
path: "/v1/monitors"
---

# Create a storm monitor: email and/or webhook alerts when a qualifying storm enters an area

`POST /v1/monitors`

## Request

- Base URL: `https://swathapi.com`
- URL: `https://swathapi.com/v1/monitors`
- Auth: HTTP bearer

Provide an area (GeoJSON geometry or bbox) plus at least one alert channel: webhook_url and/or email_alerts: true (emails go only to the account owner's address). hail_min_in defaults to 1.00. With webhook_url, the response includes webhook_secret exactly once. Costs 1 credit.

## Request body

- object
  - `name` string: Human label for the monitor
  - `geometry` object: GeoJSON Polygon or MultiPolygon in WGS84 (alternative to bbox)
  - `bbox` number[]: [west, south, east, north] in WGS84 degrees (alternative to geometry)
  - `hail_min_in` number: Minimum hail size in inches to trigger (default 1.00)
  - `wind_min_mph` number: Minimum wind speed in mph to trigger
  - `webhook_url` string: http(s) URL that receives signed alert POSTs (optional if email_alerts is true)
  - `email_alerts` boolean: Email storm alerts to the account owner's address — no other recipient is possible (default false)

## Response `201`

Monitor created (webhook_secret shown only in this response)

- MonitorWithSecret
  - `id` string: Monitor id (mon_...)
  - `name` string, nullable
  - `hail_min_in` number, nullable: Trigger threshold, inches
  - `wind_min_mph` number, nullable: Trigger threshold, mph
  - `webhook_url` string, nullable
  - `email_alerts` boolean: Email the account owner on each verified storm
  - `created_at` string, date-time
  - `geometry` object: GeoJSON MultiPolygon of the monitored area
  - `webhook_secret` string: HMAC secret (whsec_...) for verifying webhook payloads — returned only at creation

## Other responses

- `400`: Missing area, or neither webhook_url nor email_alerts provided
- `401`: Missing, invalid, or revoked API key. Fix: pass Authorization: Bearer sk_... (get a key at /v1/signup).
- `402`: Monthly credit limit reached (code credits_exhausted). Fix: upgrade via POST /v1/billing/checkout or wait for the monthly reset.
- `429`: Per-minute rate limit for the plan exceeded (code rate_limited). Retry after a short wait.

---

[API](https://skmtc.dev/swathapi/apis/swath-api.md) · [All operations](https://skmtc.dev/swathapi/apis/swath-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swathapi/apis/swath-api/revisions/7dbea40372ef?raw)