{
  "openapi": "3.1.0",
  "info": {
    "title": "WaterPulse API",
    "description": "Global water intelligence API. 9 endpoints covering US groundwater (USGS), streamflow, drought (US Drought Monitor), water quality (EPA WQP), aquifer sustainability, flood risk, global water stress, agricultural water use, and municipal supply briefs. All endpoints require x402 payment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.",
    "version": "1.0.0",
    "contact": { "url": "https://waterpulse-henna.vercel.app" }
  },
  "servers": [{ "url": "https://waterpulse-henna.vercel.app" }],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Send a GET request without this header to receive a 402 with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header."
      }
    }
  },
  "security": [{ "x402": [] }],
  "paths": {
    "/api/water/groundwater": {
      "get": {
        "summary": "Groundwater levels (USGS)",
        "description": "Real-time groundwater level readings from USGS monitoring wells. Returns depth-to-water, trend, and drought risk context for any US state. No API key required.",
        "operationId": "groundwater",
        "parameters": [
          { "name": "state", "in": "query", "required": true, "description": "Two-letter US state code — e.g. CA, TX, AZ, FL, KS", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "description": "Number of monitoring sites (5, 10, or 20)", "schema": { "type": "integer", "default": 10 } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Groundwater intelligence" },
          "402": { "description": "Payment required — x402 USDC on Base" }
        },
        "x-bazaar": {
          "price_usd": 0.08,
          "model": "claude-haiku-4-5-20251001",
          "data_sources": ["USGS National Water Information System"],
          "tags": ["groundwater", "usgs", "water-table", "aquifer", "drought", "well-levels"]
        }
      }
    },
    "/api/water/streamflow": {
      "get": {
        "summary": "Streamflow — river discharge (USGS)",
        "description": "Real-time river and stream discharge from USGS gauge stations. Returns flow conditions, flood stage context, and low-flow drought signals. No API key required.",
        "operationId": "streamflow",
        "parameters": [
          { "name": "state", "in": "query", "description": "Two-letter US state code — e.g. CO, OR, TN", "schema": { "type": "string" } },
          { "name": "site", "in": "query", "description": "USGS site number — e.g. 09380000 (Colorado River at Lees Ferry)", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Streamflow intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.05,
          "model": "claude-haiku-4-5-20251001",
          "data_sources": ["USGS Instantaneous Values Water Services"],
          "tags": ["streamflow", "usgs", "river", "discharge", "flood", "gauge"]
        }
      }
    },
    "/api/water/drought": {
      "get": {
        "summary": "Drought status (US Drought Monitor)",
        "description": "Current US drought status from the US Drought Monitor. Returns D0-D4 category breakdown by percent area, 12-week trend, and agricultural/municipal/wildfire impact assessment.",
        "operationId": "drought",
        "parameters": [
          { "name": "state", "in": "query", "description": "Two-letter US state code — omit for national view", "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Drought intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.08,
          "model": "claude-haiku-4-5-20251001",
          "data_sources": ["US Drought Monitor (NDMC/USDA/NOAA)"],
          "tags": ["drought", "us-drought-monitor", "D0-D4", "water-scarcity", "agricultural-drought"]
        }
      }
    },
    "/api/water/quality": {
      "get": {
        "summary": "Water quality (EPA WQP + USGS)",
        "description": "Water quality parameters from EPA Water Quality Portal and USGS. Returns contaminant levels versus EPA MCLs with health context and recommended action.",
        "operationId": "waterQuality",
        "parameters": [
          { "name": "state", "in": "query", "required": true, "description": "Two-letter US state code — e.g. MI, OH, PA", "schema": { "type": "string" } },
          { "name": "parameter", "in": "query", "description": "nitrates | phosphorus | ph | lead | arsenic | bacteria | pfas | turbidity", "schema": { "type": "string", "default": "nitrates" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Water quality intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.08,
          "model": "claude-haiku-4-5-20251001",
          "data_sources": ["EPA Water Quality Portal", "USGS NWIS"],
          "tags": ["water-quality", "epa", "contaminants", "pfas", "lead", "nitrates", "drinking-water"]
        }
      }
    },
    "/api/water/aquifer": {
      "get": {
        "summary": "Aquifer sustainability analysis",
        "description": "Deep analysis of major US aquifer systems. Returns depletion rates, recharge deficit, agricultural dependency, regulatory outlook, investment implications, and sustainability score. Covers Ogallala, Central Valley, Floridan, Edwards, and 30+ US aquifers.",
        "operationId": "aquifer",
        "parameters": [
          { "name": "aquifer", "in": "query", "required": true, "description": "Aquifer name — e.g. Ogallala, Central Valley, Floridan, Edwards, High Plains", "schema": { "type": "string" } },
          { "name": "state", "in": "query", "description": "State code for USGS data enrichment — e.g. KS, TX, CA", "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Aquifer sustainability intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.15,
          "model": "claude-sonnet-4-6",
          "data_sources": ["USGS NWIS", "web synthesis"],
          "tags": ["aquifer", "ogallala", "groundwater-depletion", "water-rights", "sustainability", "sgma"]
        }
      }
    },
    "/api/water/flood-risk": {
      "get": {
        "summary": "Flood risk intelligence",
        "description": "Real-time flood risk combining USGS stream gauge data, upstream conditions, and FEMA flood zone context. Returns current river conditions, 72-hour outlook, and property guidance for owners, insurers, and emergency planners.",
        "operationId": "floodRisk",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "description": "City, county, or river — e.g. Nashville TN, Mississippi River Iowa", "schema": { "type": "string" } },
          { "name": "state", "in": "query", "description": "Two-letter US state code for USGS data — e.g. TN, IA, TX", "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Flood risk intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.15,
          "model": "claude-sonnet-4-6",
          "data_sources": ["USGS NWIS", "FEMA NFIP", "web synthesis"],
          "tags": ["flood-risk", "fema", "usgs", "flood-zone", "nfip", "emergency", "property-risk"]
        }
      }
    },
    "/api/water/global-stress": {
      "get": {
        "summary": "Global water stress by country/basin",
        "description": "Country and basin-level water stress intelligence. Covers freshwater availability, groundwater depletion, transboundary conflict risk, climate trajectory, and investment/operational implications for any region globally.",
        "operationId": "globalStress",
        "parameters": [
          { "name": "region", "in": "query", "required": true, "description": "Country, region, or river basin — e.g. India, Middle East, Nile Basin, Murray-Darling", "schema": { "type": "string" } },
          { "name": "focus", "in": "query", "description": "agriculture | municipal | industrial | conflict | investment | all", "schema": { "type": "string", "default": "all" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Global water stress intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.15,
          "model": "claude-sonnet-4-6",
          "data_sources": ["WRI Aqueduct", "FAO AQUASTAT", "NASA GRACE", "web synthesis"],
          "tags": ["global-water", "water-stress", "scarcity", "transboundary", "esg", "mena", "south-asia"]
        }
      }
    },
    "/api/water/agriculture-use": {
      "get": {
        "summary": "Agricultural water use intelligence",
        "description": "Irrigation demand, water rights curtailments, and farm water cost intelligence for any US state. Combines USGS groundwater, US Drought Monitor, and USDA data.",
        "operationId": "agricultureUse",
        "parameters": [
          { "name": "state", "in": "query", "required": true, "description": "Two-letter US state code — e.g. CA, ID, NE, WA, CO", "schema": { "type": "string" } },
          { "name": "crop", "in": "query", "description": "Crop type — e.g. alfalfa, cotton, corn, almonds, rice", "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Agricultural water intelligence" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.15,
          "model": "claude-sonnet-4-6",
          "data_sources": ["USGS NWIS", "US Drought Monitor", "USDA", "web synthesis"],
          "tags": ["agriculture-water", "irrigation", "water-rights", "curtailment", "farm-water", "usda"]
        }
      }
    },
    "/api/water/supply-brief": {
      "get": {
        "summary": "Municipal water supply brief",
        "description": "Comprehensive water supply intelligence for any US city — reservoir storage, utility outlook, rate trajectory, infrastructure investment, and 5-year risk rating. Replaces a $2,000 water risk consulting report.",
        "operationId": "supplyBrief",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "description": "City or metro — e.g. Phoenix AZ, Las Vegas NV, Atlanta GA, Denver CO", "schema": { "type": "string" } },
          { "name": "state", "in": "query", "description": "Two-letter state code for data enrichment", "schema": { "type": "string" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": { "description": "Water supply brief" },
          "402": { "description": "Payment required" }
        },
        "x-bazaar": {
          "price_usd": 0.20,
          "model": "claude-sonnet-4-6",
          "data_sources": ["USGS NWIS", "US Drought Monitor", "utility data", "web synthesis"],
          "tags": ["water-supply", "utility", "reservoir", "municipal-water", "supply-brief", "risk-rating"]
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI specification",
        "description": "Returns this OpenAPI specification. Free endpoint — no payment required.",
        "operationId": "getOpenApiSpec",
        "security": [],
        "responses": { "200": { "description": "OpenAPI JSON spec" } }
      }
    }
  }
}