{"openapi":"3.1.0","info":{"title":"Biomassia API","version":"1.0.0","description":"Biomass Power Analysis API - Comprehensive biomass energy potential assessment,\nfeedstock logistics optimization, carbon neutrality verification, and environmental impact analysis.\n","contact":{"name":"Harmonias Support","url":"https://harmonias.org/support"},"license":{"name":"Proprietary","url":"https://harmonias.org/license"}},"servers":[{"url":"https://biomassia.harmonias.org","description":"Production"}],"tags":[{"name":"Biomass Analysis","description":"Biomass power potential and impact assessment"},{"name":"Logistics","description":"Feedstock procurement and transportation optimization"},{"name":"Carbon","description":"Carbon neutrality verification"},{"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"},"example":{"status":"healthy","service":"biomassia","version":"1.0.0","timestamp":"2024-01-15T10:30:00Z"}}}}},"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"},"example":{"name":"Biomassia API","version":"1.0.0","description":"Biomass Power Analysis API","endpoints":[{"path":"/api/v1/biomass/potential","method":"POST","description":"Calculate biomass power potential"}],"rateLimits":{"free":"100 requests/day, 10 requests/minute","basic":"1,000 requests/day, 50 requests/minute","pro":"10,000 requests/day, 100 requests/minute"}}}}}}}},"/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/biomass/potential":{"post":{"tags":["Biomass Analysis"],"summary":"Calculate Biomass Power Potential","operationId":"calculateBiomassPotential","description":"Analyzes biomass power generation potential based on location, scale,\nfeedstock type, and resource availability. Returns capacity estimates,\nfeasibility scores, and environmental impact assessment.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BiomassPotentialInput"},"examples":{"woodChips":{"summary":"Wood chip biomass plant","value":{"location":{"lat":35.6812,"lon":139.7671,"prefecture":"Tokyo"},"scale":"utility","type":"direct_combustion","feedstock":{"type":"wood_chips","availability":"high","annualSupply":50000,"supplyRadius":100}}},"agriculturalWaste":{"summary":"Agricultural waste plant","value":{"location":{"lat":34.6937,"lon":135.5023,"prefecture":"Osaka"},"scale":"community","type":"gasification","feedstock":{"type":"agricultural_waste","availability":"medium","annualSupply":20000,"supplyRadius":50}}}}}}},"responses":{"200":{"description":"Biomass potential analysis results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BiomassPotentialResponse"},"examples":{"success":{"summary":"Successful analysis","value":{"success":true,"basic":{"capacity":{"value":10,"unit":"MW"},"capacityFactor":0.85,"feedstockSecurity":{"score":0.8,"risk":"low"},"feasibility":{"overall":"feasible","score":0.75},"environmental":{"riskLevel":"low","carbonNeutral":true,"sustainability":"high"}},"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, feedstock"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid API key","message":"The provided API key is invalid or inactive"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"example":{"error":"Rate limit exceeded","message":"Rate limit exceeded. Resets at 2024-01-15T11:00:00Z","resetAt":"2024-01-15T11:00:00Z","tier":"free"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Internal server error","message":"Unknown error"}}}}}}},"/api/v1/biomass/feedstock-logistics":{"post":{"tags":["Logistics"],"summary":"Analyze Feedstock Logistics","operationId":"analyzeFeedstockLogistics","description":"Optimizes feedstock procurement, transportation routes, and storage\nrequirements for biomass plants.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedstockLogisticsInput"},"example":{"plantLocation":{"lat":35.6812,"lon":139.7671},"annualDemand":50000,"feedstockSources":[{"location":{"lat":35.7812,"lon":139.8671},"type":"wood_chips","capacity":30000},{"location":{"lat":35.5812,"lon":139.6671},"type":"wood_chips","capacity":25000}]}}}},"responses":{"200":{"description":"Logistics optimization results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedstockLogisticsResponse"},"example":{"success":true,"data":{"optimalRoutes":[{"sourceIndex":0,"distance":15.2,"transportCost":125000}],"totalTransportCost":280000,"storageRequirements":{"capacity":5000,"cost":500000}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: plantLocation, annualDemand, feedstockSources"}}}}}}},"/api/v1/biomass/carbon-neutrality":{"post":{"tags":["Carbon"],"summary":"Verify Carbon Neutrality","operationId":"verifyCarbonNeutrality","description":"Performs full lifecycle carbon analysis to verify carbon neutrality\nof biomass operations including feedstock sourcing, transportation,\nand plant operation.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarbonNeutralityInput"},"example":{"biomassType":"wood_chips","annualConsumption":50000,"transportation":{"distance":50,"mode":"truck"},"plantOperation":{"efficiency":0.35,"auxiliaryPower":0.05}}}}},"responses":{"200":{"description":"Carbon neutrality verification results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarbonNeutralityResponse"},"example":{"success":true,"data":{"isNeutral":true,"netEmissions":-1500,"lifecycle":{"feedstockEmissions":2000,"transportEmissions":800,"operationEmissions":500,"carbonSequestration":-4800}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: biomassType, annualConsumption, transportation, plantOperation"}}}}}}},"/api/v1/biomass/impact-assessment":{"post":{"tags":["Biomass Analysis"],"summary":"Assess Environmental Impact","operationId":"assessBiomassImpact","description":"Comprehensive environmental and social impact assessment for\nbiomass power plant configurations.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BiomassPlantConfig"},"example":{"location":{"lat":35.6812,"lon":139.7671,"prefecture":"Tokyo"},"plantCapacity":10,"feedstockType":"wood_chips","operationMode":"baseload"}}}},"responses":{"200":{"description":"Impact assessment results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpactAssessmentResponse"},"example":{"success":true,"data":{"environmental":{"airQuality":"moderate","waterUsage":"low","landUse":5.2},"social":{"jobs":25,"communityImpact":"positive"}},"tier":"free"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid request","message":"Missing required fields: location, plantCapacity"}}}}}}},"/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 biomass energy projects.\n","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisInput"},"example":{"capacity":10,"installationCost":50000000,"maintenanceCostPerYear":2000000,"electricityPrice":15,"capacityFactor":0.85,"projectLifespan":20}}}},"responses":{"200":{"description":"ROI analysis results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROIAnalysisResponse"},"example":{"success":true,"data":{"roi":0.156,"paybackPeriod":8.5,"npv":25000000,"irr":0.12,"lcoe":0.08}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Missing required fields: capacity, installationCost, maintenanceCostPerYear"}}}}}}},"/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":{"EnergyType":{"type":"string","enum":["biomass","solar","wind","hydro","geothermal","nuclear","gas"],"description":"Type of energy source"},"BiomassType":{"type":"string","enum":["wood_chips","wood_pellets","agricultural_waste","municipal_waste","algae","dedicated_crops"],"description":"Type of biomass feedstock"},"BiomassConversionType":{"type":"string","enum":["direct_combustion","gasification","pyrolysis","anaerobic_digestion","co_firing"],"description":"Biomass conversion technology"},"PlantScale":{"type":"string","enum":["residential","community","industrial","utility"],"description":"Scale of the power plant"},"MeasurementUnit":{"type":"string","enum":["kW","MW","GW","kWh","MWh","GWh","tCO2","kg","tonnes"],"description":"Unit of measurement"},"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"},"AvailabilityLevel":{"type":"string","enum":["low","medium","high","very_high"],"description":"Resource availability level"},"TransportMode":{"type":"string","enum":["truck","rail","ship","pipeline"],"description":"Transportation mode"},"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude"},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude"},"prefecture":{"type":"string","description":"Prefecture/region name"}}},"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","properties":{"path":{"type":"string"},"method":{"type":"string"},"description":{"type":"string"}}}},"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","description":"Error type"},"message":{"type":"string","description":"Human-readable error message"},"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"]}}},"BiomassPotentialInput":{"type":"object","required":["location","scale","type","feedstock"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"scale":{"$ref":"#/components/schemas/PlantScale"},"type":{"$ref":"#/components/schemas/BiomassConversionType"},"feedstock":{"type":"object","required":["type","availability"],"properties":{"type":{"$ref":"#/components/schemas/BiomassType"},"availability":{"$ref":"#/components/schemas/AvailabilityLevel"},"annualSupply":{"type":"number","description":"Annual supply in tonnes"},"supplyRadius":{"type":"number","description":"Supply radius in km"}}}}},"FeedstockLogisticsInput":{"type":"object","required":["plantLocation","annualDemand","feedstockSources"],"properties":{"plantLocation":{"$ref":"#/components/schemas/Location"},"annualDemand":{"type":"number","description":"Annual demand in tonnes"},"feedstockSources":{"type":"array","items":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/Location"},"type":{"$ref":"#/components/schemas/BiomassType"},"capacity":{"type":"number"}}}}}},"CarbonNeutralityInput":{"type":"object","required":["biomassType","annualConsumption","transportation","plantOperation"],"properties":{"biomassType":{"$ref":"#/components/schemas/BiomassType"},"annualConsumption":{"type":"number","description":"Annual consumption in tonnes"},"transportation":{"type":"object","required":["distance","mode"],"properties":{"distance":{"type":"number","description":"Average transport distance in km"},"mode":{"$ref":"#/components/schemas/TransportMode"}}},"plantOperation":{"type":"object","required":["efficiency"],"properties":{"efficiency":{"type":"number","minimum":0,"maximum":1},"auxiliaryPower":{"type":"number"}}}}},"BiomassPlantConfig":{"type":"object","required":["location","plantCapacity"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"plantCapacity":{"type":"number","description":"Plant capacity in MW"},"feedstockType":{"$ref":"#/components/schemas/BiomassType"},"operationMode":{"type":"string","enum":["baseload","peaking","flexible"]}}},"ROIAnalysisInput":{"type":"object","required":["capacity","installationCost","maintenanceCostPerYear"],"properties":{"capacity":{"type":"number","description":"Capacity in MW"},"installationCost":{"type":"number","description":"Total installation cost"},"maintenanceCostPerYear":{"type":"number","description":"Annual maintenance cost"},"electricityPrice":{"type":"number","description":"Electricity price per kWh"},"capacityFactor":{"type":"number","minimum":0,"maximum":1},"projectLifespan":{"type":"integer","description":"Project lifespan in years"}}},"BiomassPotentialResponse":{"type":"object","properties":{"success":{"type":"boolean"},"basic":{"type":"object","properties":{"capacity":{"type":"object","properties":{"value":{"type":"number"},"unit":{"$ref":"#/components/schemas/MeasurementUnit"}}},"capacityFactor":{"type":"number"},"feedstockSecurity":{"type":"object","properties":{"score":{"type":"number"},"risk":{"$ref":"#/components/schemas/RiskLevel"}}},"feasibility":{"type":"object","properties":{"overall":{"$ref":"#/components/schemas/FeasibilityRating"},"score":{"type":"number"}}},"environmental":{"type":"object","properties":{"riskLevel":{"$ref":"#/components/schemas/RiskLevel"},"carbonNeutral":{"type":"boolean"},"sustainability":{"type":"string"}}}}},"detailed":{"type":"object","description":"Available for paid tiers"},"tier":{"type":"string","enum":["free","basic","pro"]}}},"FeedstockLogisticsResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"optimalRoutes":{"type":"array","items":{"type":"object"}},"totalTransportCost":{"type":"number"},"storageRequirements":{"type":"object"}}}}},"CarbonNeutralityResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"isNeutral":{"type":"boolean"},"netEmissions":{"type":"number"},"lifecycle":{"type":"object"}}}}},"ImpactAssessmentResponse":{"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","description":"Return on investment"},"paybackPeriod":{"type":"number","description":"Payback period in years"},"npv":{"type":"number","description":"Net present value"},"irr":{"type":"number","description":"Internal rate of return"},"lcoe":{"type":"number","description":"Levelized cost of energy"}}}}}}},"security":[{"ApiKeyAuth":[]}]}