DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY
API reference
Ten protected capability routes and four operational endpoints verified against router.go and OpenAPI.
On this page 4 sections
#Authentication
All ten capability routes require an appropriately scoped gateway key via X-API-Key or Authorization: Bearer. On GET /v1/datasets, the caller must hold the scope for every requested dataset before any dataset handler executes.
#Product endpoints (10 routes)
GET
/v1/datasetsMulti-category orchestration in one request (200 OK or 207 Multi-Status)GET/v1/weatherCurrent weather observations (weather.v1)GET/v1/forecastBounded modeled forecast points (forecast.v1)GET/v1/forecast/dailySampled forecast UTC daily summaries (forecast.daily.v1)GET/v1/geocodeForward and reverse geocoding (location.v1)GET/v1/astronomyCalculated solar and lunar events (astronomy.v1)GET/v1/air-qualityCAMS model air-quality forecasts (air_quality.v1 · experimental)GET/v1/historyERA5 reanalysis for 1–7 UTC dates (history.v1 · experimental)GET/v1/marineModeled wave conditions (marine.v1 · experimental)GET/v1/alertsOfficial US NWS active alerts (alerts.v1 · experimental)#Operational endpoints
| Path | Access | Purpose |
|---|---|---|
GET /health | Public probe | Process health (bypasses client rate limit) |
GET /readiness | Public probe | Dependency & configured capability readiness (fails if required Redis is down) |
GET /liveness | Public probe | Process liveness |
GET /metrics | Loopback + Bearer token | Prometheus metrics (disabled by default; requires APP_METRICS_MODE=loopback and APP_METRICS_TOKEN >=32 chars) |
#Contract sources
Source-of-truth files: docs/openapi.yaml (default lean_v1 contract), docs/openapi.experimental.yaml (full_experimental contract), internal/routing/router.go, internal/routing/datasets.go and per-product handlers in internal/capability/.
Canonical contracts:
docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.