{"openapi":"3.1.0","info":{"title":"Hydria API","version":"1.0.0","description":"Hydroelectric Power Analysis API - Comprehensive hydroelectric assessment including\nflow analysis, environmental impact, pumped storage optimization, and economic analysis.\n","contact":{"name":"Harmonias Support","url":"https://harmonias.org/support"},"license":{"name":"Proprietary","url":"https://harmonias.org/license"}},"servers":[{"url":"https://hydria.harmonias.org","description":"Production"}],"tags":[{"name":"Hydro Analysis","description":"Hydroelectric power potential assessment"},{"name":"Flow Analysis","description":"River flow patterns and seasonal variations"},{"name":"Environmental","description":"Environmental impact and mitigation"},{"name":"Storage","description":"Pumped storage and grid integration"},{"name":"Economics","description":"Financial analysis and ROI calculations"},{"name":"System","description":"Health checks and API information"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Health Check","operationId":"healthCheck","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"healthy":{"summary":"Service operational","value":{"status":"healthy","service":"hydria","version":"1.0.0","timestamp":"2024-01-15T10:30:00Z"}},"degraded":{"summary":"Service degraded (partial outage)","value":{"status":"degraded","service":"hydria","version":"1.0.0","timestamp":"2024-01-15T10:30:00Z","message":"Flow analysis service temporarily unavailable"}}}}}}},"security":[]}},"/api/v1/info":{"get":{"tags":["System"],"summary":"API Information","operationId":"getApiInfo","responses":{"200":{"description":"API information and available endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInfo"}}}}}}},"/api/v1/disclaimer":{"get":{"tags":["System"],"summary":"API Disclaimer","operationId":"getDisclaimer","responses":{"200":{"description":"Important disclaimers and limitations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Disclaimer"}}}}}}},"/api/v1/hydro/potential":{"post":{"tags":["Hydro Analysis"],"summary":"Calculate Hydroelectric Potential","operationId":"calculateHydroPotential","description":"Analyzes hydroelectric power generation potential based on location, scale,\ntype, and water resources.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HydroPotentialInput"},"examples":{"reservoir":{"summary":"Large reservoir dam (Kurobe-style)","value":{"location":{"lat":36.5,"lon":138.5,"prefecture":"Nagano"},"scale":"utility","type":"reservoir","waterResources":{"head":100,"flowRate":50,"annualVolume":500000000}}},"runOfRiver":{"summary":"Run-of-river small hydro","value":{"location":{"lat":35,"lon":137,"prefecture":"Gifu"},"scale":"small","type":"run_of_river","waterResources":{"head":30,"flowRate":10,"annualVolume":100000000}}},"pumpedStorage":{"summary":"Pumped-storage facility (Okutataragi-style)","value":{"location":{"lat":35.2,"lon":136.8,"prefecture":"Hyogo"},"scale":"utility","type":"pumped_storage","waterResources":{"head":423,"flowRate":180,"annualVolume":1200000000}}},"microHydro":{"summary":"Micro hydropower (village-scale)","value":{"location":{"lat":36.8,"lon":138.3,"prefecture":"Nagano"},"scale":"micro","type":"run_of_river","waterResources":{"head":15,"flowRate":2,"annualVolume":8000000}}}}}}},"responses":{"200":{"description":"Hydroelectric potential analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HydroPotentialResponse"},"examples":{"utilityScaleSuccess":{"summary":"Utility-scale reservoir (highly feasible)","value":{"success":true,"basic":{"capacity":{"value":30,"unit":"MW"},"capacityFactor":0.45,"feasibility":{"overall":"highly_feasible","score":0.82},"environmental":{"riskLevel":"moderate","riskScore":0.55},"comparison":{"solarEquivalent":150,"windEquivalent":75}},"tier":"free"}},"pumpedStorageSuccess":{"summary":"Pumped-storage analysis (high capacity)","value":{"success":true,"basic":{"capacity":{"value":1932,"unit":"MW"},"capacityFactor":0.15,"feasibility":{"overall":"feasible","score":0.68},"environmental":{"riskLevel":"high","riskScore":0.72},"comparison":{"solarEquivalent":12880,"windEquivalent":6440}},"tier":"free"}},"microHydroSuccess":{"summary":"Micro hydro (village-scale feasibility)","value":{"success":true,"basic":{"capacity":{"value":0.25,"unit":"MW"},"capacityFactor":0.58,"feasibility":{"overall":"feasible","score":0.76},"environmental":{"riskLevel":"low","riskScore":0.28},"comparison":{"solarEquivalent":1.25,"windEquivalent":0.625}},"tier":"free"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, scale, type, waterResources"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/hydro/flow-analysis":{"post":{"tags":["Flow Analysis"],"summary":"Analyze River Flow Patterns","operationId":"analyzeHydroFlow","description":"Analyzes river flow patterns and seasonal variations for hydroelectric planning.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowAnalysisInput"},"examples":{"francisTurbine":{"summary":"Francis turbine for medium-head dam","value":{"location":{"lat":36.5,"lon":138.5,"prefecture":"Nagano"},"riverData":{"catchmentArea":500,"meanAnnualFlow":25,"seasonalVariation":"high"},"turbineSpecs":{"type":"francis","capacity":30,"efficiency":0.92}}},"kaplanTurbine":{"summary":"Kaplan turbine for low-head run-of-river","value":{"location":{"lat":35.8,"lon":139.2,"prefecture":"Gunma"},"riverData":{"catchmentArea":1200,"meanAnnualFlow":85,"seasonalVariation":"moderate"},"turbineSpecs":{"type":"kaplan","capacity":18,"efficiency":0.9}}},"peltonTurbine":{"summary":"Pelton turbine for high-head alpine site","value":{"location":{"lat":36.9,"lon":137.6,"prefecture":"Toyama"},"riverData":{"catchmentArea":180,"meanAnnualFlow":8,"seasonalVariation":"extreme"},"turbineSpecs":{"type":"pelton","capacity":12,"efficiency":0.88}}}}}}},"responses":{"200":{"description":"Flow analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowAnalysisResponse"},"example":{"success":true,"data":{"seasonalOutput":{"spring":8500,"summer":12000,"fall":7500,"winter":4000},"firmPower":15,"peakPower":30,"annualGeneration":118000,"flowDurationCurve":[{"exceedance":10,"flow":60},{"exceedance":50,"flow":25},{"exceedance":90,"flow":8}]},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, riverData, turbineSpecs"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/hydro/environmental-impact":{"post":{"tags":["Environmental"],"summary":"Assess Environmental Impact","operationId":"assessEnvironmentalImpact","description":"Assesses environmental impact and recommends mitigation measures.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentalImpactInput"},"examples":{"salmonRiver":{"summary":"Salmon-bearing river requiring fish passage","value":{"location":{"lat":36.5,"lon":138.5,"prefecture":"Nagano"},"riverData":{"ecosystem":"temperate_river","fishSpecies":["salmon","trout","ayu"]}}},"alpineStream":{"summary":"Alpine stream with minimal impact","value":{"location":{"lat":36.9,"lon":137.7,"prefecture":"Toyama"},"riverData":{"ecosystem":"alpine_stream","fishSpecies":["char","iwana"]}}},"lowlandRiver":{"summary":"Lowland river with high biodiversity","value":{"location":{"lat":34.8,"lon":135.5,"prefecture":"Osaka"},"riverData":{"ecosystem":"lowland_river","fishSpecies":["carp","catfish","eel","sweetfish"]}}}}}}},"responses":{"200":{"description":"Environmental impact assessment results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentalImpactResponse"},"example":{"success":true,"data":{"fishPassage":{"required":true,"type":"fish_ladder","cost":5000000},"sedimentManagement":{"strategy":"flushing","frequency":"annual","impact":"moderate"},"minimumFlow":5,"overallImpact":"moderate","mitigation":[{"measure":"fish_passage","cost":5000000,"effectiveness":"high"},{"measure":"environmental_flow","cost":2000000,"effectiveness":"medium"}]},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/hydro/pumped-storage":{"post":{"tags":["Storage"],"summary":"Analyze Pumped Storage","operationId":"analyzePumpedStorage","description":"Analyzes pumped storage arbitrage and renewable energy integration.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PumpedStorageInput"},"examples":{"mediumScale":{"summary":"Medium-scale pumped storage (500MW)","value":{"facilitySpecs":{"capacity":500,"head":300,"roundTripEfficiency":0.78},"marketConditions":{"peakPrice":25,"offPeakPrice":8,"renewablePenetration":0.35}}},"largeScale":{"summary":"Large-scale pumped storage (1932MW, Okutataragi-style)","value":{"facilitySpecs":{"capacity":1932,"head":423,"roundTripEfficiency":0.82},"marketConditions":{"peakPrice":30,"offPeakPrice":6,"renewablePenetration":0.48}}},"highRenewable":{"summary":"Grid with high renewable penetration","value":{"facilitySpecs":{"capacity":800,"head":350,"roundTripEfficiency":0.8},"marketConditions":{"peakPrice":35,"offPeakPrice":4,"renewablePenetration":0.65}}}}}}},"responses":{"200":{"description":"Pumped storage analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PumpedStorageResponse"},"example":{"success":true,"data":{"arbitrageRevenue":35000000,"ancillaryServices":15000000,"renewableIntegration":{"value":"high","curtailmentReduction":0.25},"cyclesPerYear":300,"economics":{"totalRevenue":50000000,"operatingCost":10000000,"netRevenue":40000000}},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/economics/roi-analysis":{"post":{"tags":["Economics"],"summary":"Economic ROI Analysis","operationId":"analyzeROI","description":"Calculates return on investment, payback period, and financial\nmetrics for hydroelectric projects.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisInput"},"examples":{"mediumHydro":{"summary":"Medium-scale hydropower (30MW)","value":{"capacity":30,"installationCost":100000000,"maintenanceCostPerYear":1000000,"electricityPrice":12,"capacityFactor":0.45,"projectLifespan":50}},"microHydro":{"summary":"Micro hydropower (250kW, village-scale)","value":{"capacity":0.25,"installationCost":800000,"maintenanceCostPerYear":25000,"electricityPrice":15,"capacityFactor":0.58,"projectLifespan":30}},"largeReservoir":{"summary":"Large reservoir dam (300MW, Kurobe-style)","value":{"capacity":300,"installationCost":1500000000,"maintenanceCostPerYear":15000000,"electricityPrice":10,"capacityFactor":0.42,"projectLifespan":80}},"pumpedStorage":{"summary":"Pumped-storage facility (1932MW)","value":{"capacity":1932,"installationCost":8000000000,"maintenanceCostPerYear":80000000,"electricityPrice":18,"capacityFactor":0.15,"projectLifespan":60}}}}}},"responses":{"200":{"description":"ROI analysis results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisResponse"},"example":{"success":true,"data":{"roi":0.108,"paybackPeriod":12,"npv":45000000,"irr":0.085,"lcoe":0.035}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/data-sources":{"get":{"summary":"Get data-sources","description":"Auto-generated stub. Schema/responses/parameters TBD.\nVerify path matches the actual mounted URL (sub-router prefix may be missing).\n","x-stub":true,"responses":{"200":{"description":"Successful response (schema TBD)"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key in format: Bearer <api_key>"}},"schemas":{"HydroType":{"type":"string","enum":["run_of_river","reservoir","pumped_storage","diversion"],"description":"Type of hydroelectric system"},"TurbineType":{"type":"string","enum":["francis","kaplan","pelton","crossflow","bulb"],"description":"Type of turbine"},"PlantScale":{"type":"string","enum":["micro","small","medium","large","utility"],"description":"Scale of the power plant"},"RiskLevel":{"type":"string","enum":["very_low","low","moderate","high","very_high"],"description":"Risk assessment level"},"FeasibilityRating":{"type":"string","enum":["not_feasible","marginally_feasible","feasible","highly_feasible"],"description":"Project feasibility rating"},"SeasonalVariation":{"type":"string","enum":["low","moderate","high","extreme"],"description":"Seasonal flow variation level"},"EcosystemType":{"type":"string","enum":["temperate_river","tropical_river","alpine_stream","lowland_river"],"description":"River ecosystem type"},"MeasurementUnit":{"type":"string","enum":["kW","MW","m3/s","meters","MWh","km2"],"description":"Unit of measurement"},"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"prefecture":{"type":"string"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"service":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"ApiInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"array","items":{"type":"object"}},"rateLimits":{"type":"object"}}},"Disclaimer":{"type":"object","properties":{"service":{"type":"string"},"disclaimer":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"success":{"type":"boolean","default":false}}},"RateLimitError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"resetAt":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["free","basic","pro"]}}},"HydroPotentialInput":{"type":"object","required":["location","scale","type","waterResources"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"scale":{"$ref":"#/components/schemas/PlantScale"},"type":{"$ref":"#/components/schemas/HydroType"},"waterResources":{"type":"object","required":["head","flowRate"],"properties":{"head":{"type":"number","description":"Head in meters"},"flowRate":{"type":"number","description":"Flow rate in m3/s"},"annualVolume":{"type":"number","description":"Annual volume in m3"}}}}},"FlowAnalysisInput":{"type":"object","required":["location","riverData","turbineSpecs"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"riverData":{"type":"object","properties":{"catchmentArea":{"type":"number"},"meanAnnualFlow":{"type":"number"},"seasonalVariation":{"$ref":"#/components/schemas/SeasonalVariation"}}},"turbineSpecs":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/TurbineType"},"capacity":{"type":"number"},"efficiency":{"type":"number"}}}}},"EnvironmentalImpactInput":{"type":"object","required":["location","riverData"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"riverData":{"type":"object","properties":{"ecosystem":{"$ref":"#/components/schemas/EcosystemType"},"fishSpecies":{"type":"array","items":{"type":"string"}}}}}},"PumpedStorageInput":{"type":"object","required":["facilitySpecs","marketConditions"],"properties":{"facilitySpecs":{"type":"object","properties":{"capacity":{"type":"number"},"head":{"type":"number"},"roundTripEfficiency":{"type":"number"}}},"marketConditions":{"type":"object","properties":{"peakPrice":{"type":"number"},"offPeakPrice":{"type":"number"},"renewablePenetration":{"type":"number"}}}}},"ROIAnalysisInput":{"type":"object","required":["capacity","installationCost","maintenanceCostPerYear"],"properties":{"capacity":{"type":"number"},"installationCost":{"type":"number"},"maintenanceCostPerYear":{"type":"number"},"electricityPrice":{"type":"number"},"capacityFactor":{"type":"number"},"projectLifespan":{"type":"integer"}}},"HydroPotentialResponse":{"type":"object","properties":{"success":{"type":"boolean"},"basic":{"type":"object"},"detailed":{"type":"object"},"tier":{"type":"string","enum":["free","basic","pro"]}}},"FlowAnalysisResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"EnvironmentalImpactResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"PumpedStorageResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"tier":{"type":"string"}}},"ROIAnalysisResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"roi":{"type":"number"},"paybackPeriod":{"type":"number"},"npv":{"type":"number"},"irr":{"type":"number"},"lcoe":{"type":"number"}}}}}}},"security":[{"ApiKeyAuth":[]}]}