{
  "openapi": "3.0.0",
  "info": {
    "title": "AskWeather.ai Weather Intelligence API",
    "description": "Derived weather insights for AI agents, automation tools, and modern applications. Returns scores, risk levels, and plain-English summaries — not raw weather data.",
    "version": "1.0.0",
    "contact": {
      "url": "https://askweather.ai/for-ai"
    }
  },
  "servers": [
    { "url": "https://askweather.ai" }
  ],
  "paths": {
    "/api/rain-risk": {
      "get": {
        "summary": "Rain risk for a city",
        "description": "Returns the rain probability and risk level for today in the specified US city.",
        "operationId": "getRainRisk",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "City slug e.g. houston-tx, dallas-tx, chicago-il",
            "schema": { "type": "string", "example": "houston-tx" }
          }
        ],
        "responses": {
          "200": {
            "description": "Rain risk data",
            "content": {
              "application/json": {
                "example": {
                  "city": "Houston, TX",
                  "rain_probability": 0.72,
                  "risk_level": "high",
                  "summary": "High chance of rain this afternoon in Houston, TX."
                }
              }
            }
          },
          "400": { "description": "city param missing" },
          "404": { "description": "city not found" }
        }
      }
    },
    "/api/outdoor-score": {
      "get": {
        "summary": "Outdoor activity score for a city",
        "description": "Returns a 1-10 outdoor suitability score derived from precipitation, temperature, and wind.",
        "operationId": "getOutdoorScore",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "City slug e.g. houston-tx, dallas-tx, chicago-il",
            "schema": { "type": "string", "example": "dallas-tx" }
          }
        ],
        "responses": {
          "200": {
            "description": "Outdoor score data",
            "content": {
              "application/json": {
                "example": {
                  "city": "Dallas, TX",
                  "score": 9,
                  "label": "Great",
                  "summary": "Great conditions for outdoor activities in Dallas, TX today."
                }
              }
            }
          },
          "400": { "description": "city param missing" },
          "404": { "description": "city not found" }
        }
      }
    },
    "/api/weather-brief": {
      "get": {
        "summary": "Plain-English weather summary for a city",
        "description": "Returns a one-sentence weather summary with high, low, and conditions for today.",
        "operationId": "getWeatherBrief",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "City slug e.g. houston-tx, dallas-tx, chicago-il",
            "schema": { "type": "string", "example": "chicago-il" }
          }
        ],
        "responses": {
          "200": {
            "description": "Weather brief data",
            "content": {
              "application/json": {
                "example": {
                  "city": "Chicago, IL",
                  "high": 47,
                  "low": 24,
                  "conditions": "Snow, Partially cloudy",
                  "brief": "Snow, Partially cloudy in Chicago, IL today with a high of 47°F and low of 24°F."
                }
              }
            }
          },
          "400": { "description": "city param missing" },
          "404": { "description": "city not found" }
        }
      }
    }
  }
}