API

Integrate with verified forecasts.

Programmatic access to live forecasts, evidence chains, verification scores, and replay artifacts. Strict schema versioning. Deterministic response envelopes.

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

Server-Sent Events (SSE) with automatic reconnection. Each event is a complete JSON payload matching the corresponding REST endpoint schema.

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

Public tier: 60 requests / minute.
No API key required for public read endpoints.
Streaming endpoints: 1 concurrent connection per IP.

Download contracts (JSON)