# Swath API — agent integration guide

Storm-verified property intelligence API. Hail events measured by NOAA radar (never forecasts),
webhook alerts for registered coverage areas, per-property exposure reports.

## Self-serve signup (no human needed)
POST https://swathapi.com/v1/signup {"email": "<owner-email>"} -> { "api_key": "sk_..." } (shown once; free plan 100 credits/mo)
Auth: Authorization: Bearer <api_key>

## Core flow
1. POST /v1/monitors {"bbox":[w,s,e,n], "hail_min_in":1.0, "webhook_url":"..."} -> save webhook_secret
   (or/and "email_alerts": true — Swath emails the account owner's address on each verified storm;
   alerts can only go to accounts.email, there is no recipient parameter)
2. Receive storm.verified webhook (HMAC: X-Swath-Signature: t=<unix>,v1=hmac_sha256(secret, t+"."+body))
3. GET /v1/swaths/{storm_id}/properties?roof_age_min=10&owner_occupied=true -> affected parcels,
   each with exposure {hail_in, score 0-1} at that location. Filters: roof_age_min, roof_material,
   owner_occupied, year_built_before/after, value_min/max, min_exposure_score, limit, offset.
   Billing: 1 credit per property returned + 25 credits per record fetched fresh from the parcel
   vendor (10-credit minimum). The response's billing object shows the actual charge.
4. GET /v1/swaths/{storm_id}/properties/quote (1 credit) -> cost preview before a big report:
   total_cached (filtered count, no rows), fresh_possible, fresh_estimate (labeled ESTIMATE;
   billing uses actuals only). Same filters as the report, minus limit/offset.
5. POST /v1/swaths/{storm_id}/email-report -> emails a branded report summary to the account's own
   email (the signup address; no recipient parameter). Summary = 1 credit; add ?limit=N (max 50) to
   include the top N properties by exposure, billed exactly like the report endpoint.
6. GET /v1/property?address=... for single-property enrichment.
7. GET /v1/usage for credit consumption (report = 1/property returned +25/fresh-fetched, min 10;
   quote = 1; property = 2; others = 1; failures never billed).

## Plans
- free: 100 credits/mo, hard stop at the limit, cached property data only (no live vendor fetches).
  A report with limit > remaining credits is rejected 402 — lower limit or use the quote endpoint.
- developer: $199/mo, 40,000 credits included. scale: $999/mo, 600,000 credits included.
  Both get full live parcel coverage; past the included credits, usage meters as overage
  ($0.008/credit developer, $0.005/credit scale) on the monthly invoice.

## Notes for agents
- Storm ids look like sw_xxxx; pass either storm id or swath id to /v1/swaths/{id}/*.
- GET /v1/storms?since=<ISO>&bbox=w,s,e,n&type=hail lists recent verified events.
- Webhook deliveries are exactly-once per (storm, monitor); retried 8x with exponential backoff.