{ "openapi": "3.0.3", "info": { "title": "SteelHead Addiction Public API", "description": "Real-time Steelhead Alley fishing conditions, composite indices, regional rollups, and river forecasts. AI-native query endpoints for anglers and agents.", "version": "1.0", "contact": { "name": "SteelHead Addiction Support", "url": "https://steelheadaddiction.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://steelheadaddiction.com" } ], "paths": { "/api/public/v1/alley-index": { "get": { "summary": "Get composite Alley Index", "description": "Retrieve the current composite Steelhead Alley Index score, trend, and sub-index calculations.", "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", "Slipping", "Blown" ] }, "trend": { "type": "string", "enum": [ "rising", "falling", "flat" ] }, "trend_change_24h": { "type": "integer" }, "headline": { "type": "string" }, "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", "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": { "summary": "Get regional conditions summary", "description": "Retrieve a roll-up of fishing conditions, regional picks, watch lists, and active storm events across a region or the whole Alley.", "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" }, "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", "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/rivers/{slug}": { "get": { "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" ] }, "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" ] }, "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": { "updated_at": { "type": "string", "format": "date-time" }, "next_update_at": { "type": "string", "format": "date-time" }, "canonical_url": { "type": "string" }, "attribution": { "type": "string" } }, "additionalProperties": false, "required": [ "updated_at", "next_update_at", "canonical_url", "attribution" ] }, "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" } }, "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" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": [ "code", "message" ] } }, "additionalProperties": false, "required": [ "error" ] } } } }