Versioning & deprecation policy READ THIS FIRST

Additive changes are never breaking and ship without notice. New endpoints, new optional request parameters, and new response fields can appear at any time — don't write client code that rejects an unrecognized field or a response object with more keys than you expected.
Breaking changes are versioned: /v1 → /v2. A breaking change (removing/renaming a field, changing a field's type or semantics, removing an endpoint, changing an error code's meaning) never happens in place on /v1 — it ships as /v2 alongside the still-working /v1.
/v1 gets a minimum 90-day deprecation window once /v2 ships, announced in this changelog, via email to registered API-key owners, and with a Deprecation + Sunset response header (RFC 8594) on every /v1 response during the window.
Pre-launch exception (in effect now): the handful of breaking entries below (2026-07-04) shipped in place on /v1 without a deprecation window — there are no external production integrations yet to break. This policy, and the 90-day//v2 rule above, is what governs every change from here forward.
Security fixes are the one exception to advance notice — a vulnerability fix ships immediately, documented after the fact in this changelog.

Release history 25 ENTRIES

BREAKING GET /v1/usage's operations field changed shape from a flat map keyed by operation name to a paginated object: {items: [...], total_count, next_cursor}. Page with operations_limit / operations_cursor.
BREAKING Response fields renamed to snake_case across the API: every estimate=true response (estimatedCost→estimated_cost, overageRate→overage_rate), and GET /v1/usage (spendCap→spend_cap, untilCap→until_cap, overagePolicy→overage_policy incl. nested fields, lastUpdated→last_updated, costPerCall→cost_per_call).
BREAKING Async job "failed" bodies (GET /v1/exports/:id, GET /v1/verify/report/:id) and POST /v1/webhooks/:id/test's failure body now put a machine-readable code in error (e.g. export_generation_failed, webhook_unreachable) with the human-readable text moved to a new message field — previously error held the human sentence directly.
ADDED New GET /v1/usage/export — CSV download of the complete (unpaginated) per-operation usage breakdown. Free (0 credits).
ADDED A daily per-day credit timeseries added to GET /v1/usage's response.
ADDED Canonical error-code registry: every error response is now {error, message, request_id} with error drawn from a fixed, documented code enum (see definitions.Error in the OpenAPI spec).
ADDED Every data endpoint now returns a real data_timestamp (or equivalent named field) reflecting the latest source scan/run time. Cacheable GETs support conditional requests — send back If-None-Match / If-Modified-Since and get 304 Not Modified.
ADDED Idempotency-Key header support on POST /v1/alerts/subscribe, /v1/webhooks, /v1/verify, /v1/exports, /v1/portfolio/locations — replaying the same key within 24h returns the original response with Idempotent-Replay: true instead of re-executing (and re-billing) the request.
ADDED Webhook payloads now carry a schema_version field; a per-webhook delivery audit log (GET /v1/webhooks/:id/deliveries) and manual redelivery (POST /v1/webhooks/:id/deliveries/:deliveryId/redeliver) were added; auto-disable after repeated failures now also emails your account's Admin/Manager team members.
ADDED Official Node.js (@hailsentinel/api-client) and Python (hailsentinel-api) SDKs, including a webhook HMAC signature verification helper — see the SDKs section above.

ADDED PUT /v1/alerts/:id — update or pause an existing alert subscription.
ADDED Alert subscriptions now actually fire: a live evaluator matches every active subscription against real-time detections and delivers a signed webhook, respecting status: "paused".
ADDED POST/GET/PUT/DELETE /v1/areas — polygon or point+radius monitored areas, with alert evaluation wired in.
ADDED POST /v1/portfolio/locations bulk upsert (CSV/JSON, chunked, per-plan quota) and GET /v1/portfolio/impacts — which portfolio assets intersected hail detections on a given date.
ADDED GET /v1/events — event-day summaries by date range/region.
ADDED POST /v1/exports — async bulk export (detections/swaths/reports) to CSV, GeoJSON, or Parquet via a signed, time-limited download URL.
ADDED The alert.resolved webhook event now carries explicit all-clear semantics: threat_cleared_at, max_size_during_event, duration_seconds.

ADDED A detection_quality (HDQI) block added to detail=advanced responses and to standalone GET /v1/coverage — a physics-based radar-coverage quality prior for a location, not an empirical detection rate.
ADDED GET /v1/storms (active storm cells) and GET /v1/storms/{track_id} (track history).
ADDED GET /v1/tiles/{layer}/{z}/{x}/{y} — radar map tiles under API-key auth with per-key metering.
ADDED GET /v1/hail/swaths — GeoJSON footprint polygons per event-day, with size-tier contours.
ADDED POST /v1/verify — synchronous date-of-loss verification verdicts (banded results, ground-truth corroboration, detection-quality context). POST /v1/verify/report — an async, brandable PDF version of the same verdict, delivered via a signed URL.

ADDED Distributed per-key rate limiting, fail-closed credit metering, warm Cloud Run instances + graceful shutdown + response compression, a full automated test harness with an OpenAPI-vs-mounted-routes contract check, API key rotation + structured audit logging, Stripe subscription-status enforcement, and a security hardening pass (production CORS allowlist, webhook SSRF redirect-chain guard, security headers, request-ID coverage).
ADDED GET /v1/hail/nowcast — T+15/30/45-minute probabilities. detail=advanced gained an impact block (kinetic energy, impact angle, wind context) on hail/current and hail/history.
ADDED GET /v1/outlooks/spc — categorical + hail probability outlook by day. GET /v1/warnings — active/historical severe warnings and SPC watches. GET /v1/hail/outlook — Day 1–7 blended hail risk with an hourly Day-1 strip.