{"openapi":"3.0.3","info":{"title":"Harmonias API","description":"Renewable Energy Investment Optimization API\n\n⚠️ **IMPORTANT DISCLAIMER**: This API provides estimates only - NOT for final investment decisions.\n\nHarmonias is designed for preliminary screening and educational purposes.\nAlways consult qualified professionals before making investment decisions.\n","version":"0.2.0","contact":{"email":"support@ppn-hub.com","url":"https://harmonias.ppn-hub.com"},"license":{"name":"Proprietary","url":"https://harmonias.ppn-hub.com/terms"}},"servers":[{"url":"https://renewio.harmonias.org","description":"Production"},{"url":"http://localhost:8787","description":"Development server"}],"tags":[{"name":"Health","description":"Service health and status"},{"name":"ROI","description":"ROI calculation endpoints"},{"name":"Projects","description":"Saved projects management"},{"name":"Templates","description":"Parameter templates"},{"name":"Export","description":"Result export functionality"},{"name":"Advanced","description":"Advanced analysis features"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"harmonias"},"version":{"type":"string","example":"0.2.0"}}}}}}},"operationId":"getHealth"}},"/api/v1/info":{"get":{"tags":["Health"],"summary":"API information","security":[],"responses":{"200":{"description":"API metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInfo"}}}}},"operationId":"getInfo"}},"/api/v1/roi/calculate":{"post":{"tags":["ROI"],"summary":"Calculate ROI for renewable energy project","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROICalculationRequest"}}}},"responses":{"200":{"description":"ROI calculation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ROICalculationResponse"}}}}},"operationId":"createRoiCalculate"}},"/api/v1/roi/capacity-factor":{"get":{"tags":["ROI"],"summary":"Get capacity factor for location","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"},"description":"Latitude coordinate in decimal degrees","example":35.6812},{"name":"lon","in":"query","required":true,"schema":{"type":"number"},"description":"Longitude coordinate in decimal degrees","example":139.7671},{"name":"energyType","in":"query","required":true,"schema":{"type":"string","enum":["solar","wind","geothermal","biomass","hydro"]},"description":"Energy type","example":"solar"}],"responses":{"200":{"description":"Capacity factor retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityFactorResponse"}}}}},"operationId":"getRoiCapacityFactor"}},"/api/v1/roi/compare":{"post":{"tags":["ROI"],"summary":"Compare multiple scenarios","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioComparisonRequest"}}}},"responses":{"200":{"description":"Scenario comparison completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioComparisonResponse"}}}}},"operationId":"createRoiCompare"}},"/api/v1/roi/calculate-with-impact":{"post":{"tags":["ROI"],"summary":"Calculate ROI with environmental impact assessment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratedCalculationRequest"}}}},"responses":{"200":{"description":"Integrated calculation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratedCalculationResponse"}}}}},"operationId":"createRoiCalculateWithImpact"}},"/api/v1/projects/save":{"post":{"tags":["Projects"],"summary":"Save calculation result as project","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProjectRequest"}}}},"responses":{"201":{"description":"Project saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProjectResponse"}}}}},"operationId":"createProjectsSave"}},"/api/v1/projects/list":{"get":{"tags":["Projects"],"summary":"List saved projects","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number for pagination (starts at 1)","example":1},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Page size","example":20},{"name":"type","in":"query","schema":{"type":"string","enum":["roi","compare","sensitivity","bulk"]},"description":"Resource type filter","example":"standard"},{"name":"energyType","in":"query","schema":{"type":"string","enum":["solar","wind","geothermal","biomass","hydro","mixed"]},"description":"Energy type","example":"solar"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["created_at","npv","irr","name"],"default":"created_at"},"description":"Sort by","example":"created_at"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"},"description":"Sort order","example":"DESC"}],"responses":{"200":{"description":"Project list retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}}},"operationId":"getProjectsList"}},"/api/v1/projects/{projectId}":{"get":{"tags":["Projects"],"summary":"Get project by ID","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id","example":"proj_abc123"}],"responses":{"200":{"description":"Project retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDetail"}}}}},"operationId":"getProjectsProjectId"},"patch":{"tags":["Projects"],"summary":"Update project metadata","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id","example":"proj_abc123"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectRequest"}}}},"responses":{"200":{"description":"Project updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDetail"}}}}},"operationId":"updateProjectsProjectId"},"delete":{"tags":["Projects"],"summary":"Delete project","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project id","example":"proj_abc123"}],"responses":{"204":{"description":"Project deleted"}},"operationId":"deleteProjectsProjectId"}},"/api/v1/projects/compare":{"post":{"tags":["Projects"],"summary":"Compare saved projects","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectIds"],"properties":{"projectIds":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":10}}}}}},"responses":{"200":{"description":"Project comparison completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectComparisonResponse"}}}}},"operationId":"createProjectsCompare"}},"/api/v1/templates/list":{"get":{"tags":["Templates"],"summary":"List templates","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Category filter","example":"general"},{"name":"publicOnly","in":"query","schema":{"type":"boolean","default":false},"description":"Public only","example":"true"}],"responses":{"200":{"description":"Template list retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateListResponse"}}}}},"operationId":"getTemplatesList"}},"/api/v1/templates/{templateId}":{"get":{"tags":["Templates"],"summary":"Get template by ID","parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string"},"description":"Template id","example":"tmpl_solar_residential"}],"responses":{"200":{"description":"Template retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}}},"operationId":"getTemplatesTemplateId"}},"/api/v1/templates/save":{"post":{"tags":["Templates"],"summary":"Save new template","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveTemplateRequest"}}}},"responses":{"201":{"description":"Template saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}}},"operationId":"createTemplatesSave"}},"/{projectId}/export":{"get":{"summary":"Get projectId/export","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,"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response (schema TBD)"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key sent via header (X-API-Key). Obtain from the PPN Hub developer portal."}},"schemas":{"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}}},"EnergyType":{"type":"string","enum":["solar","wind","geothermal","biomass","hydro"]},"ROICalculationRequest":{"type":"object","required":["location","energyType","system","investment","financial"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"energyType":{"$ref":"#/components/schemas/EnergyType"},"system":{"type":"object","required":["capacity"],"properties":{"capacity":{"type":"number"},"capacityFactor":{"type":"number"},"degradationRate":{"type":"number"}}},"investment":{"type":"object","required":["initialCost"],"properties":{"initialCost":{"type":"number"},"landCost":{"type":"number"},"gridConnectionCost":{"type":"number"}}},"financial":{"type":"object","required":["sellPrice"],"properties":{"sellPrice":{"type":"number"},"discountRate":{"type":"number","default":0.05},"period":{"type":"integer","default":20},"subsidyAmount":{"type":"number"},"taxRate":{"type":"number","default":0.3}}}}},"ROICalculationResponse":{"type":"object","properties":{"roi":{"type":"object","properties":{"npv":{"type":"number"},"irr":{"type":"number"},"roi":{"type":"number"},"paybackPeriod":{"type":"number"},"profitMargin":{"type":"number"},"lcoe":{"type":"number"}}},"energy":{"type":"object"},"financial":{"type":"object"},"cashflows":{"type":"array","items":{"type":"object"}},"risks":{"type":"object"},"disclaimer":{"type":"string"},"metadata":{"type":"object"}}},"BulkCalculationRequest":{"type":"object","required":["calculations"],"properties":{"calculations":{"type":"array","items":{"allOf":[{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}},{"$ref":"#/components/schemas/ROICalculationRequest"}]},"minItems":1,"maxItems":200},"options":{"type":"object","properties":{"parallel":{"type":"boolean","default":true},"stopOnError":{"type":"boolean","default":false},"includeFullCashflow":{"type":"boolean","default":false}}}}},"BulkCalculationResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["success","error"]},"roi":{"type":"object"},"error":{"type":"string"},"processingTime":{"type":"integer"}}}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"successful":{"type":"integer"},"failed":{"type":"integer"}}},"quotaUsed":{"type":"integer"}}},"SensitivityAnalysisRequest":{"type":"object","required":["baseCase","sensitivityParameters"],"properties":{"baseCase":{"$ref":"#/components/schemas/ROICalculationRequest"},"sensitivityParameters":{"type":"array","items":{"type":"object","required":["parameter","range"],"properties":{"parameter":{"type":"string"},"label":{"type":"string"},"range":{"type":"object","required":["min","max","step"],"properties":{"min":{"type":"number"},"max":{"type":"number"},"step":{"type":"number"}}}}},"minItems":1,"maxItems":5}}},"SensitivityAnalysisResponse":{"type":"object","properties":{"disclaimer":{"type":"string"},"disclaimerType":{"type":"string","example":"sensitivity_analysis"},"baseCase":{"type":"object"},"sensitivityResults":{"type":"array","items":{"type":"object"}},"summary":{"type":"object"}}},"SaveProjectRequest":{"type":"object","required":["name","calculationType","inputParams","outputResults"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000},"calculationType":{"type":"string","enum":["roi","compare","sensitivity","bulk"]},"inputParams":{"type":"object"},"outputResults":{"type":"object"},"tags":{"type":"array","items":{"type":"string"}}}},"SaveProjectResponse":{"type":"object","properties":{"projectId":{"type":"string"},"message":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ProjectListResponse":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummary"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"ProjectSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"calculationType":{"type":"string"},"energyType":{"type":"string"},"npv":{"type":"number"},"irr":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}},"ProjectDetail":{"allOf":[{"$ref":"#/components/schemas/ProjectSummary"},{"type":"object","properties":{"description":{"type":"string"},"inputParams":{"type":"object"},"outputResults":{"type":"object"}}}]},"UpdateProjectRequest":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"isFavorite":{"type":"boolean"},"isArchived":{"type":"boolean"}}},"ProjectComparisonResponse":{"type":"object","properties":{"disclaimer":{"type":"string"},"comparison":{"type":"array","items":{"type":"object"}},"differenceAnalysis":{"type":"object"}}},"Template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"defaults":{"type":"object"},"isPublic":{"type":"boolean"},"useCount":{"type":"integer"}}},"TemplateListResponse":{"type":"object","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}},"SaveTemplateRequest":{"type":"object","required":["name","defaults"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"defaults":{"type":"object"},"isPublic":{"type":"boolean"}}},"ExportRequest":{"type":"object","required":["projectId","format"],"properties":{"projectId":{"type":"string"},"format":{"type":"string","enum":["csv","json","xlsx","pdf"]},"options":{"type":"object","properties":{"includeCashflow":{"type":"boolean"},"includeCharts":{"type":"boolean"},"locale":{"type":"string","enum":["ja","en"]}}}}},"ExportResponse":{"type":"object","properties":{"exportId":{"type":"string"},"downloadUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"format":{"type":"string"},"fileSize":{"type":"integer"}}},"ApiInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"object"},"disclaimer":{"type":"string"}}},"CapacityFactorResponse":{"type":"object","properties":{"capacityFactor":{"type":"number"},"region":{"type":"string"},"regionName":{"type":"string"},"energyType":{"type":"string"},"location":{"$ref":"#/components/schemas/Location"},"note":{"type":"string"}}},"ScenarioComparisonRequest":{"type":"object","required":["location","scenarios"],"properties":{"location":{"$ref":"#/components/schemas/Location"},"scenarios":{"type":"array","minItems":2,"maxItems":10}}},"ScenarioComparisonResponse":{"type":"object","properties":{"comparison":{"type":"array"},"recommendation":{"type":"object"},"disclaimer":{"type":"string"}}},"IntegratedCalculationRequest":{"allOf":[{"$ref":"#/components/schemas/ROICalculationRequest"},{"type":"object","properties":{"impactAssessment":{"type":"object"}}}]},"IntegratedCalculationResponse":{"allOf":[{"$ref":"#/components/schemas/ROICalculationResponse"},{"type":"object","properties":{"environmentalImpact":{"type":"object"},"overallAssessment":{"type":"object"}}}]}}}}