API documentation.

Base URL

https://api.hailsentinel.com/v1

Authentication

All requests require a Bearer token in the Authorization header. Obtain your API key from the developer dashboard after signing up.

Rotating a key

Rotate a key from the console (Settings > API Keys > Rotate) at any time — you'll get a brand-new key with the same scopes, shown once. The old key isn't cut off immediately: it keeps working for a 30-day grace period so you have time to deploy the new one, then stops authenticating on its own.

Rate limits

Every API key is capped at 60 requests/minute, raised by agreement for high-volume workspaces. Workspaces differ by monthly query allowance and webhook access, not request rate. Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset. Repeated invalid-key attempts are locked out separately (by source IP and by the key being guessed) and return 429 too_many_failed_attempts.

Response format

All responses are JSON, returned as the resource directly (e.g. a cells array for detections, an hourly array for forecasts) — no envelope wrapper. Errors include a machine-readable error code and a human-readable message.

Idempotent retries

Pass an Idempotency-Key header (any string, up to 255 characters) on POST /v1/alerts/subscribe, /v1/webhooks, /v1/verify, /v1/exports, or /v1/portfolio/locations and a retry after a dropped connection is safe: the same key replayed within 24 hours returns the exact original response — Idempotent-Replay: true header included — instead of creating a second resource or billing you twice. A second request with the same key while the first is still in flight gets 409 idempotency_key_in_progress; briefly retry. Failed (5xx) attempts are never cached, so a retry after an infra hiccup runs fresh rather than replaying the failure for 24 hours.

Freshness & caching

Every market-data GET (hail/current, hail/forecast, hail/risk, hail/nowcast, outlooks/spc, warnings, hail/outlook, hail/swaths, storms, coverage, tiles, hail/history, events) returns a real data_timestamp (or an equivalently-named field where the source has its own freshness concept — data_as_of, fetched_at, model.run_time) and an ETag header. Send it back as If-None-Match on your next request and get 304 Not Modified with an empty body instead of re-downloading bytes you already have — a 304 is billed the same as the 200 it mirrors, so it saves bandwidth, not credits. Verified freshness: radar-fusion-derived endpoints (current conditions, history, swaths, storms, events, warnings, nowcast) refresh on the storm-scanner's real ~2-minute scan cadence, typically current within 5 minutes; hail/forecast and outlooks/spc run hourly (short-range-model-driven); hail/risk's climatology component refreshes weekly; hail/outlook (Day 2-7) refreshes daily. coverage is a static radar-geometry prior with no scan cadence, so it has no data_timestamp — not an oversight.

# Get current hail activity near Denver, CO
curl "https://api.hailsentinel.com/v1/hail/current\
?lat=39.7392&lon=-104.9903&radius_km=25" \
  -H "Authorization: Bearer hs_live_abc123..."

{
  "active": true,
  "detail": "standard",
  "summary": {
    "total_cells": 3,
    "max_size_mm": 32,
    "closest_cell_km": 4.2,
    "max_size_category": "quarter"
  },
  "cells": [
    {
      "geohash5": "9xj64",
      "lat": 39.7412,
      "lon": -104.9876,
      "distance_km": 4.2,
      "age_seconds": 95,
      "last_detected": "2026-02-28T18:42:00Z",
      "scan_count": 4,
      "hail": {
        "estimated_size_mm": 32,
        "ml_predicted_size_mm": 28,
        "size_category": "quarter",
        "confidence": 0.87
      }
    }
  ],
  "query": { "lat": 39.7392, "lon": -104.9903, "radius_km": 25, "lookback_minutes": 30 }
}