API

Integrate with verified forecasts.

Public beta access to the live JSON artifacts currently deployed in /data, plus replay, evidence, and verification endpoints exposed through the worker.

Simple Technical

For developers

This page describes our programming interface (API) for software developers who want to build applications using HazardPulse data.

If you just want to check the forecasts, visit the Live forecasts page instead.

Switch to Technical mode above to see the full API documentation.

Core endpoints

Method	Endpoint	Description	Auth
`GET`	`/api/v1/live/pulse`	Current probabilities for all hazards	None
`GET`	`/api/v1/live/{hazard}`	Detail for a specific hazard (earthquake, hurricane, tornado)	None
`GET`	`/api/v1/forecast/{forecast_id}`	Full forecast record by ID	None
`GET`	`/api/v1/evidence/{provenance_id}`	Provenance envelope by ID	None
`GET`	`/api/v1/gates/{gate_decision_id}`	Gate decision record by ID	None
`GET`	`/api/v1/verification/summary`	Rolling verification scores	None
`GET`	`/api/v1/registry/models`	Active model versions and metadata	None
`GET`	`/api/v1/replay/{forecast_id}`	Replay artifact for deterministic re-run	None

Streaming endpoints

Method	Endpoint	Description	Protocol
`GET`	`/stream/live/pulse`	Real-time forecast updates	SSE
`GET`	`/stream/ops/status`	System health events	SSE

These SSE routes currently emit a snapshot payload when the connection opens. Clients that want polling-style freshness should reconnect on their own cadence.

Data contracts

All responses follow versioned contracts. Breaking changes require a version bump.

HazardForecastV1

forecast_idString

hazard_typeearthquake | hurricane | tornado

issued_atTimestamp (ISO 8601)

valid_from / valid_toTimestamp

probabilityFloat (0.0-1.0)

confidence_lo / confidence_hiFloat

delta_from_prevFloat

model_versionString

features_digestString (SHA-256)

provenance_idString

gate_decision_idString

ProvenanceEnvelopeV1

provenance_idString

trace_idString

input_hashString (SHA-256)

output_hashString (SHA-256)

source_refsList[String]

transform_refsList[String]

signed_atTimestamp

GateDecisionV1

gate_decision_idString

decisionpass | block | degrade

blocking_reasonsList[String]

warningsList[String]

emitted_atTimestamp

VerificationRecordV1

verification_idString

forecast_idString

outcome_observedBool

brier_contribFloat

log_scoreFloat

calibration_binString

API principles

Versioning

All endpoints are versioned (/api/v1/).
Breaking changes require a new version with explicit deprecation window.
Schema fields are never removed within a version; new fields may be added.

Response envelopes

Every response includes meta.version, meta.generated_at, and meta.cache_ttl.
Error responses include error.code, error.message, and error.trace_id.
All timestamps are ISO 8601 UTC.

Caching

Live endpoints: max-age=300 (5 minutes).
Evidence/replay: max-age=31536000, immutable (1 year).
Registry/verification: max-age=3600 (1 hour).

Rate limits

No API key is required for public read endpoints.
No hard public rate limit is enforced today; abusive traffic may be throttled.
Streaming endpoints are best-effort beta snapshot feeds.

Download contracts (JSON)