{ "openapi": "3.1.0", "info": { "title": "MicroGrid-IQ Public Calculator API", "version": "1.0.0", "description": "Focused, stateless calculation endpoints for energy, electrical, utility, battery, dwelling-load, and explicit cash-flow arithmetic. No account or customer project data is used." }, "servers": [ { "url": "https://microgrid-iq.com", "description": "MicroGrid-IQ public calculation service" } ], "paths": { "/api/ai/calculators": { "get": { "operationId": "listMicroGridIqCalculators", "summary": "List public calculators", "responses": { "200": { "description": "Calculator catalog", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/ai/calculators/energy-use": { "post": { "operationId": "calculateEnergyUse", "summary": "Calculate energy from constant power and duration", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnergyUseInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/ac-power": { "post": { "operationId": "calculateAcPower", "summary": "Calculate single-phase or balanced three-phase AC power", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcPowerInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/voltage-drop": { "post": { "operationId": "calculateVoltageDrop", "summary": "Estimate copper-conductor voltage drop", "description": "Planning estimate only; it does not determine ampacity or code compliance.", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoltageDropInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/dwelling-load": { "post": { "operationId": "estimateDwellingLoad", "summary": "Estimate a traditional dwelling service load", "description": "Planning estimate only; adopted-code, authority, and qualified-professional review is required.", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DwellingLoadInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/utility-bill": { "post": { "operationId": "calculateUtilityBill", "summary": "Calculate a flat-rate utility bill from caller-supplied rates", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UtilityBillInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/battery-size": { "post": { "operationId": "sizeBatteryBackup", "summary": "Estimate battery energy capacity for a critical load and duration", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatterySizeInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/api/ai/calculators/cash-flow": { "post": { "operationId": "analyzeCashFlows", "summary": "Calculate metrics from explicit cash flows", "description": "Arithmetic analysis only, not tax, legal, accounting, or investment advice.", "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashFlowInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculatorSuccess" }, "400": { "$ref": "#/components/responses/InvalidInput" } } } }, "/.well-known/mcp-server.json": { "get": { "operationId": "getMicroGridIqMcpDescriptor", "summary": "Get the MCP server descriptor", "responses": { "200": { "description": "MCP server descriptor", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "responses": { "CalculatorSuccess": { "description": "Structured calculation with units, assumptions, and warnings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatorResponse" } } } }, "InvalidInput": { "description": "Invalid or incomplete calculator input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "CalculatorResponse": { "type": "object", "required": [ "calculator", "engine_version", "method_date", "result", "units", "assumptions", "warnings", "methodology_url" ], "properties": { "calculator": { "type": "string" }, "engine_version": { "type": "string" }, "method_date": { "type": "string", "format": "date" }, "result": { "type": "object", "additionalProperties": true }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "methodology_url": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } }, "EnergyUseInput": { "type": "object", "additionalProperties": false, "required": [ "power_kw", "duration_hours" ], "properties": { "power_kw": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "duration_hours": { "type": "number", "exclusiveMinimum": 0, "maximum": 87600 } } }, "AcPowerInput": { "type": "object", "additionalProperties": false, "required": [ "phase", "voltage_volts", "current_amps" ], "properties": { "phase": { "type": "string", "enum": [ "single_phase", "three_phase" ] }, "voltage_volts": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "current_amps": { "type": "number", "minimum": 0, "maximum": 1000000 }, "power_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 1 } } }, "VoltageDropInput": { "type": "object", "additionalProperties": false, "required": [ "phase", "source_voltage_volts", "current_amps", "one_way_length_ft", "copper_conductor_size" ], "properties": { "phase": { "type": "string", "enum": [ "single_phase", "three_phase" ] }, "source_voltage_volts": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "current_amps": { "type": "number", "minimum": 0, "maximum": 1000000 }, "one_way_length_ft": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "copper_conductor_size": { "type": "string", "enum": [ "14", "12", "10", "8", "6", "4", "3", "2", "1", "1/0", "2/0", "3/0", "4/0", "250", "300", "350", "400", "500" ] }, "max_voltage_drop_percent": { "type": "number", "exclusiveMinimum": 0, "maximum": 20, "default": 3 } } }, "DwellingLoadInput": { "type": "object", "additionalProperties": false, "required": [ "floor_area_sq_ft" ], "properties": { "floor_area_sq_ft": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "small_appliance_circuits": { "type": "integer", "minimum": 2, "maximum": 100, "default": 2 }, "laundry_circuits": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "fixed_appliances": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "rating_va" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "rating_va": { "type": "number", "minimum": 0, "maximum": 1000000 }, "is_fastened_in_place": { "type": "boolean", "default": true } } }, "default": [] }, "ranges": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "rating_kw" ], "properties": { "rating_kw": { "type": "number", "minimum": 0, "maximum": 1000 }, "is_built_in": { "type": "boolean" } } }, "default": [] }, "hvac_loads": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "type", "rating_va" ], "properties": { "type": { "type": "string", "enum": [ "cooling", "heating", "heat_pump" ] }, "rating_va": { "type": "number", "minimum": 0, "maximum": 10000000 }, "description": { "type": "string", "maxLength": 200 } } }, "default": [] }, "electric_heating_kw": { "type": "number", "minimum": 0, "maximum": 10000 }, "water_heater_va": { "type": "number", "minimum": 0, "maximum": 1000000 }, "pool_equipment_va": { "type": "number", "minimum": 0, "maximum": 1000000 }, "other_loads_va": { "type": "number", "minimum": 0, "maximum": 10000000 } } }, "UtilityBillInput": { "type": "object", "additionalProperties": false, "required": [ "monthly_energy_kwh", "energy_rate_per_kwh" ], "properties": { "monthly_energy_kwh": { "type": "number", "minimum": 0, "maximum": 100000000 }, "energy_rate_per_kwh": { "type": "number", "minimum": 0, "maximum": 1000 }, "fixed_monthly_charge": { "type": "number", "minimum": 0, "maximum": 1000000, "default": 0 }, "tax_rate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0 }, "other_monthly_charges": { "type": "number", "minimum": 0, "maximum": 1000000, "default": 0 }, "demand_rate_per_kw": { "type": "number", "minimum": 0, "maximum": 100000 }, "peak_demand_kw": { "type": "number", "minimum": 0, "maximum": 10000000 }, "currency_label": { "type": "string", "minLength": 1, "maxLength": 12, "default": "USD" } } }, "BatterySizeInput": { "type": "object", "additionalProperties": false, "required": [ "critical_load_kw", "backup_hours" ], "properties": { "critical_load_kw": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "backup_hours": { "type": "number", "exclusiveMinimum": 0, "maximum": 8760 }, "depth_of_discharge": { "type": "number", "exclusiveMinimum": 0, "maximum": 1, "default": 0.8 }, "safety_margin": { "type": "number", "minimum": 1, "maximum": 3, "default": 1.1 } } }, "CashFlowInput": { "type": "object", "additionalProperties": false, "required": [ "initial_investment", "annual_cash_flows", "discount_rate" ], "properties": { "initial_investment": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000 }, "annual_cash_flows": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "number", "minimum": -1000000000000, "maximum": 1000000000000 } }, "discount_rate": { "type": "number", "exclusiveMinimum": -0.99, "maximum": 10 }, "currency_label": { "type": "string", "minLength": 1, "maxLength": 12, "default": "USD" } } } } } }