{ "openapi": "3.1.0", "info": { "title": "Steelhead Almanac Public API", "description": "Real-time Steelhead Alley regional fishability, season mode, target-species context, regional rollups, and river forecasts. AI-native query endpoints for anglers and agents.", "version": "1.0", "contact": { "name": "Steelhead Almanac Support", "url": "https://steelheadalmanac.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://steelheadalmanac.com" } ], "paths": { "/api/public/v1/alley-index": { "get": { "operationId": "getAlleyIndex", "summary": "Get regional Alley fishability index", "description": "Retrieve the current regional Steelhead Alley fishability score, season mode, target species, steelhead status, trend, and sub-index calculations. In summer, high ratings describe regional warmwater fishability, not a tributary steelhead-run recommendation.", "responses": { "200": { "description": "Successful composite index response", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "data": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "label": { "type": "string", "enum": [ "Excellent", "Good", "Average", "Poor", "Blown" ] }, "trend": { "type": "string", "enum": [ "rising", "falling", "flat" ] }, "trend_change_24h": { "type": "integer" }, "headline": { "type": "string" }, "season_mode": { "type": "string", "enum": [ "steelhead", "warm_water", "transition" ], "description": "Seasonal interpretation mode for the score. Read this before treating a rating as steelhead-specific advice." }, "score_context": { "type": "string", "description": "Plain-English context explaining what the score measures in the current season." }, "primary_targets": { "type": "array", "items": { "type": "string" }, "description": "Species or species groups the current score is meant to guide." }, "steelhead_status": { "type": "string", "enum": [ "in_season", "off_season", "transition" ] }, "steelhead_targeting_advice": { "type": "string", "description": "Guidance for whether a high score should be interpreted as a tributary steelhead recommendation." }, "sub_indices": { "type": "object", "properties": { "flow": { "type": "object", "properties": { "score": { "type": "integer" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "score", "label" ] }, "clarity": { "type": "object", "properties": { "score": { "type": "integer" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "score", "label" ] }, "temp": { "type": "object", "properties": { "score": { "type": "integer" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "score", "label" ] }, "weather": { "type": "object", "properties": { "score": { "type": "integer" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "score", "label" ] } }, "additionalProperties": false, "required": [ "flow", "clarity", "temp", "weather" ] }, "forecast_7d": { "type": "array", "items": { "type": "integer" } }, "best_window": { "type": "object", "nullable": true, "properties": { "day_label": { "type": "string" }, "date": { "type": "string" }, "score": { "type": "integer" } }, "additionalProperties": false, "required": [ "day_label", "date", "score" ] }, "storm_state": { "type": "string", "enum": [ "quiet", "watching", "active", "recovering" ] }, "storm_active_buckets": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "score", "label", "trend", "trend_change_24h", "headline", "season_mode", "score_context", "primary_targets", "steelhead_status", "steelhead_targeting_advice", "sub_indices", "forecast_7d", "best_window", "storm_state", "storm_active_buckets" ] }, "meta": { "$ref": "#/components/schemas/EnvelopeMeta" } }, "additionalProperties": false, "required": [ "api_version", "data", "meta" ] } } } } } } }, "/api/public/v1/conditions/summary": { "get": { "operationId": "getConditionsSummary", "summary": "Get regional conditions summary", "description": "Retrieve a roll-up of fishing conditions, target-species context, regional picks, watch lists, and active storm events across a region or the whole Alley. In summer, high ratings describe warmwater regional fishability unless steelhead_status says otherwise.", "parameters": [ { "name": "region", "in": "query", "required": false, "description": "Filter results by regional bucket", "schema": { "type": "string", "enum": [ "oh-erie", "pa-erie", "ny-erie", "ny-ontario", "alley" ] } } ], "responses": { "200": { "description": "Successful conditions rollup summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "data": { "type": "object", "properties": { "region": { "type": "string" }, "alley_index_score": { "type": "integer", "nullable": true }, "alley_index_label": { "type": "string", "nullable": true }, "headline": { "type": "string" }, "season_mode": { "type": "string", "enum": [ "steelhead", "warm_water", "transition" ], "description": "Seasonal interpretation mode for the score. Read this before treating a rating as steelhead-specific advice." }, "score_context": { "type": "string", "description": "Plain-English context explaining what the score measures in the current season." }, "primary_targets": { "type": "array", "items": { "type": "string" }, "description": "Species or species groups the current score is meant to guide." }, "steelhead_status": { "type": "string", "enum": [ "in_season", "off_season", "transition" ] }, "steelhead_targeting_advice": { "type": "string", "description": "Guidance for whether a high score should be interpreted as a tributary steelhead recommendation." }, "top_picks": { "type": "array", "items": { "$ref": "#/components/schemas/RiverPickItem" } }, "watch_list": { "type": "array", "items": { "$ref": "#/components/schemas/RiverWatchItem" } }, "skip_list": { "type": "array", "items": { "$ref": "#/components/schemas/RiverWatchItem" } }, "five_day_forecast": { "type": "array", "items": { "$ref": "#/components/schemas/ForecastDayItem" } }, "active_storms": { "type": "array", "items": { "$ref": "#/components/schemas/StormItem" } }, "incoming_storms": { "type": "array", "items": { "$ref": "#/components/schemas/StormItem" } }, "coverage": { "type": "object", "properties": { "region": { "type": "string" }, "river_count_total": { "type": "integer" }, "river_count_reporting": { "type": "integer" } }, "additionalProperties": false, "required": [ "region", "river_count_total", "river_count_reporting" ] } }, "additionalProperties": false, "required": [ "region", "alley_index_score", "alley_index_label", "headline", "season_mode", "score_context", "primary_targets", "steelhead_status", "steelhead_targeting_advice", "top_picks", "watch_list", "skip_list", "five_day_forecast", "active_storms", "incoming_storms", "coverage" ] }, "meta": { "$ref": "#/components/schemas/EnvelopeMeta" } }, "additionalProperties": false, "required": [ "api_version", "data", "meta" ] } } } } } } }, "/api/public/v1/storm-watch": { "get": { "operationId": "getStormWatch", "summary": "Get active storm-watch state", "description": "Retrieve regional storm-watch state, active/recovering/watching buckets, affected rivers, alerts, and freshness metadata for Steelhead Alley.", "responses": { "200": { "description": "Successful storm-watch response", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "data": { "$ref": "#/components/schemas/StormWatchData" }, "meta": { "$ref": "#/components/schemas/EnvelopeMeta" } }, "additionalProperties": false, "required": [ "api_version", "data", "meta" ] } } } } } } }, "/api/public/v1/fishing-window": { "get": { "operationId": "getFishingWindow", "summary": "Get a date-specific fishing window", "description": "Retrieve one day of regional fishing-window guidance from the Steelhead Alley Index forecast, including season context, drivers, top predicted rivers, and action metadata.", "parameters": [ { "name": "date", "in": "query", "required": false, "description": "Fishing-window date: today, tomorrow, or YYYY-MM-DD", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful fishing-window response", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "data": { "$ref": "#/components/schemas/FishingWindowData" }, "meta": { "$ref": "#/components/schemas/EnvelopeMeta" } }, "additionalProperties": false, "required": [ "api_version", "data", "meta" ] } } } }, "400": { "description": "Invalid date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Forecast not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/public/v1/rivers/{slug}": { "get": { "operationId": "getRiverBySlug", "summary": "Get river details and forecast", "description": "Retrieve current conditions, historical percentiles, active storm lifecycle states, recommended gear/flies, and a 5-day forecast for a single tributary.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The unique river slug, supporting aliases (e.g. chagrin-river or chagrin)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful single river conditions response", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "example": "1.0" }, "data": { "type": "object", "properties": { "slug": { "type": "string" }, "canonical_slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "OH", "PA", "NY" ] }, "rating": { "type": "string", "enum": [ "excellent", "good", "fair", "poor", "unknown" ] }, "score": { "type": "integer", "nullable": true }, "flow_cfs": { "type": "integer", "nullable": true }, "flow_percentile": { "type": "integer", "nullable": true }, "flow_phase": { "type": "string", "enum": [ "dropping", "rising", "stable", "flat", "unknown", "low", "high", "blown" ] }, "clarity": { "type": "string", "nullable": true }, "water_temp_f": { "type": "integer", "nullable": true }, "air_temp_f": { "type": "integer", "nullable": true }, "primary_gauge_id": { "type": "string", "nullable": true }, "is_fishable": { "type": "boolean", "description": "recommended fishable — true when rating ∈ {good, excellent}" }, "summary": { "type": "string", "nullable": true }, "techniques": { "type": "array", "items": { "type": "string" } }, "recommended_flies": { "type": "array", "items": { "type": "string" } }, "lifecycle": { "type": "object", "nullable": true, "properties": { "state": { "type": "string", "enum": [ "active", "watching", "recovering" ] }, "severity": { "type": "string", "enum": [ "minor", "moderate", "major", "severe" ], "nullable": true }, "headline": { "type": "string", "nullable": true }, "expected_at": { "type": "string", "format": "date-time", "nullable": true }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "confidence_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "signals": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "state", "severity", "headline", "expected_at", "ended_at", "confidence_score", "signals" ] }, "timing": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "opening", "closing", "blown", "recovering", "stable", "unknown", "low" ] }, "current_rating": { "type": "string", "enum": [ "excellent", "good", "fair", "poor" ], "nullable": true }, "next_event": { "type": "string", "enum": [ "rises_into_range", "drops_into_range", "rises_above_range", "drops_below_range", "peaks" ], "nullable": true }, "event_at": { "type": "string", "format": "date-time", "nullable": true }, "hours_until_event": { "type": "number", "nullable": true }, "projected_peak_flow": { "type": "number", "nullable": true }, "projected_peak_at": { "type": "string", "format": "date-time", "nullable": true }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "projected_flow_6h": { "type": "number", "nullable": true }, "projected_flow_12h": { "type": "number", "nullable": true }, "projected_flow_18h": { "type": "number", "nullable": true }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "ahps", "recent_regression", "storm_pulse", "nws_qpf", "lifecycle" ] } } }, "required": [ "state", "current_rating", "next_event", "event_at", "hours_until_event", "projected_peak_flow", "projected_peak_at", "projected_flow_6h", "projected_flow_12h", "projected_flow_18h", "confidence", "sources" ] }, "wind_speed_mph": { "type": "integer", "nullable": true }, "wind_direction": { "type": "string", "enum": [ "N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW" ], "nullable": true }, "wind_classification": { "type": "string", "enum": [ "onshore", "offshore", "side" ], "nullable": true }, "wind_lake_facing_direction": { "type": "string", "enum": [ "N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW" ], "nullable": true }, "five_day_forecast": { "type": "array", "items": { "$ref": "#/components/schemas/ForecastDayItem" } }, "canonical_url": { "type": "string" } }, "additionalProperties": false, "required": [ "slug", "canonical_slug", "name", "state", "rating", "score", "flow_cfs", "flow_percentile", "flow_phase", "clarity", "water_temp_f", "air_temp_f", "primary_gauge_id", "is_fishable", "summary", "techniques", "recommended_flies", "lifecycle", "five_day_forecast", "canonical_url" ] }, "meta": { "$ref": "#/components/schemas/EnvelopeMeta" } }, "additionalProperties": false, "required": [ "api_version", "data", "meta" ] } } } }, "400": { "description": "Invalid slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "River not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "EnvelopeMeta": { "type": "object", "properties": { "observed_at": { "type": "string", "format": "date-time", "description": "Timestamp of the source observation or computation used for this answer." }, "stale_after": { "type": "string", "format": "date-time", "description": "After this timestamp, LLMs and clients should refresh the endpoint before answering." }, "updated_at": { "type": "string", "format": "date-time" }, "next_update_at": { "type": "string", "format": "date-time" }, "canonical_url": { "type": "string" }, "attribution": { "type": "string" }, "attribution_text": { "type": "string", "description": "Human-readable citation text LLM answers should include." }, "action_url": { "type": "string", "format": "uri", "description": "UTM-tagged Steelhead Almanac URL for the next user action." }, "action_label": { "type": "string", "description": "Short CTA label for the action_url." } }, "additionalProperties": false, "required": [ "observed_at", "stale_after", "updated_at", "next_update_at", "canonical_url", "attribution", "attribution_text", "action_url", "action_label" ] }, "RiverPickItem": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "rating": { "type": "string" }, "score": { "type": "integer" }, "flow_cfs": { "type": "integer", "nullable": true }, "clarity": { "type": "string", "nullable": true }, "water_temp_f": { "type": "integer", "nullable": true }, "canonical_url": { "type": "string" } }, "additionalProperties": false, "required": [ "slug", "name", "rating", "score", "flow_cfs", "clarity", "water_temp_f", "canonical_url" ] }, "RiverWatchItem": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "rating": { "type": "string" }, "score": { "type": "integer" }, "reason": { "type": "string" }, "canonical_url": { "type": "string" } }, "additionalProperties": false, "required": [ "slug", "name", "rating", "score", "reason", "canonical_url" ] }, "ForecastDayItem": { "type": "object", "properties": { "day_label": { "type": "string" }, "date": { "type": "string", "format": "date" }, "score": { "type": "integer" }, "label": { "type": "string" }, "forecast_explanation": { "type": "string" } }, "additionalProperties": false, "required": [ "day_label", "date", "score", "label" ] }, "StormItem": { "type": "object", "properties": { "region": { "type": "string" }, "region_name": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "region", "region_name", "severity", "headline" ] }, "StormWatchData": { "type": "object", "properties": { "overall_state": { "type": "string", "enum": [ "quiet", "watching", "active", "recovering" ] }, "active_region_count": { "type": "integer" }, "watching_region_count": { "type": "integer" }, "recovering_region_count": { "type": "integer" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/StormWatchRegion" } }, "summary": { "type": "string" } }, "additionalProperties": false, "required": [ "overall_state", "active_region_count", "watching_region_count", "recovering_region_count", "regions", "summary" ] }, "StormWatchRegion": { "type": "object", "properties": { "region": { "type": "string" }, "region_name": { "type": "string" }, "short_label": { "type": "string" }, "state": { "type": "string", "enum": [ "quiet", "watching", "active", "recovering" ] }, "severity": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "signals": { "type": "array", "items": { "type": "string" } }, "triggers": { "type": "array", "items": { "type": "string" } }, "affected_rivers": { "type": "array", "items": { "$ref": "#/components/schemas/StormWatchRiver" } }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/StormWatchAlert" } }, "computed_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "region", "region_name", "short_label", "state", "severity", "headline", "signals", "triggers", "affected_rivers", "alerts", "computed_at" ] }, "StormWatchRiver": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string", "nullable": true }, "flow_cfs": { "type": "integer", "nullable": true }, "precipitation_1h": { "type": "number", "nullable": true }, "flow_rate_6h_ago": { "type": "integer", "nullable": true }, "flow_rise_factor": { "type": "number", "nullable": true }, "is_raining": { "type": "boolean" }, "is_rising": { "type": "boolean" }, "mrms_rate_hr": { "type": "number", "nullable": true }, "canonical_url": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "slug", "name", "flow_cfs", "precipitation_1h", "flow_rate_6h_ago", "flow_rise_factor", "is_raining", "is_rising", "mrms_rate_hr", "canonical_url" ] }, "StormWatchAlert": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "nullable": true }, "area_desc": { "type": "string", "nullable": true }, "nws_office": { "type": "string", "nullable": true }, "impacted_river_slugs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "id", "event_type", "headline", "description", "severity", "expires_at", "area_desc", "nws_office", "impacted_river_slugs" ] }, "FishingWindowData": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "day_label": { "type": "string" }, "score": { "type": "integer" }, "label": { "type": "string" }, "confidence_pct": { "type": "integer", "nullable": true }, "drivers": { "type": "object", "properties": { "flow": { "type": "string", "nullable": true }, "precip": { "type": "string", "nullable": true }, "temp": { "type": "string", "nullable": true }, "clarity": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true } }, "additionalProperties": false }, "best_window": { "type": "string", "nullable": true }, "forecast_explanation": { "type": "string" }, "recommendation": { "type": "string" }, "season_mode": { "type": "string", "enum": [ "steelhead", "warm_water", "transition" ] }, "score_context": { "type": "string" }, "primary_targets": { "type": "array", "items": { "type": "string" } }, "steelhead_status": { "type": "string", "enum": [ "in_season", "off_season", "transition" ] }, "steelhead_targeting_advice": { "type": "string" }, "top_rivers": { "type": "array", "items": { "$ref": "#/components/schemas/FishingWindowRiver" } } }, "additionalProperties": false, "required": [ "date", "day_label", "score", "label", "confidence_pct", "drivers", "best_window", "forecast_explanation", "recommendation", "season_mode", "score_context", "primary_targets", "steelhead_status", "steelhead_targeting_advice", "top_rivers" ] }, "FishingWindowRiver": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "rating": { "type": "string" }, "score": { "type": "integer" }, "confidence": { "type": "integer", "nullable": true }, "flow_pred": { "type": "number", "nullable": true }, "temp_pred": { "type": "number", "nullable": true }, "clarity_pred": { "type": "string", "nullable": true }, "canonical_url": { "type": "string" } }, "additionalProperties": false, "required": [ "slug", "name", "rating", "score", "confidence", "flow_pred", "temp_pred", "clarity_pred", "canonical_url" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": [ "code", "message" ] } }, "additionalProperties": false, "required": [ "error" ] } } } }