{ "openapi": "3.1.0", "info": { "title": "Mamble Calculator API", "version": "1.0.0", "description": "Financial calculator API powering the Mamble loan calculator platform. All endpoints accept JSON and return deterministic numeric results. Compatible as a ChatGPT Action backend and as a standalone REST API.", "contact": { "name": "Mamble" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-proprietary" } }, "security": [], "servers": [ { "url": "https://calculators.mamblellc.com", "description": "Primary server (set via OPENAPI_SERVER_URL)" }, { "url": "http://localhost:3001", "description": "Local development server" } ], "tags": [ { "name": "mortgage", "description": "Mortgage and home buying calculators" }, { "name": "insurance", "description": "Mortgage insurance calculators" }, { "name": "refinance", "description": "Refinance analysis calculators" }, { "name": "comparison", "description": "Loan comparison calculators" }, { "name": "affordability", "description": "Home affordability calculators" } ], "paths": { "/api/calculators/dti": { "post": { "operationId": "calculate_dti", "summary": "Calculate DTI ratio", "description": "Calculates front-end and back-end debt-to-income ratios. Returns qualification status and remaining debt capacity.", "tags": [ "mortgage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthlyIncome": { "type": "number", "minimum": 0 }, "housingPayment": { "default": 0, "type": "number", "minimum": 0 }, "carPayment": { "default": 0, "type": "number", "minimum": 0 }, "creditCards": { "default": 0, "type": "number", "minimum": 0 }, "studentLoans": { "default": 0, "type": "number", "minimum": 0 }, "otherDebts": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "monthlyIncome" ], "additionalProperties": false }, "example": { "monthlyIncome": 8000, "housingPayment": 2000, "carPayment": 400, "creditCards": 200, "studentLoans": 200, "otherDebts": 0 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "monthlyIncome": { "type": "number", "description": "Gross monthly income before taxes ($) — echoed from inputs for widget pre-population" }, "totalDebts": { "type": "number", "description": "Sum of all monthly debt payments ($)" }, "frontEndDTI": { "type": "number", "description": "Housing payment as a percentage of gross monthly income" }, "backEndDTI": { "type": "number", "description": "All debts as a percentage of gross monthly income" }, "qualifies": { "type": "boolean", "description": "True when back-end DTI is at or below 43% (conventional loan threshold)" }, "remainingCapacity": { "type": "number", "description": "Monthly debt capacity remaining before hitting 43% back-end DTI threshold ($)" } }, "required": [ "monthlyIncome", "totalDebts", "frontEndDTI", "backEndDTI", "qualifies", "remainingCapacity" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/mortgage-payment": { "post": { "operationId": "calculate_mortgage_payment", "summary": "Calculate mortgage payment", "description": "Calculates the full monthly mortgage payment breakdown. Set includeSchedule=true to include the full amortization schedule.", "tags": [ "mortgage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "monthlyHOA": { "default": 0, "type": "number", "minimum": 0 }, "includePMI": { "default": true, "type": "boolean" }, "pmiRatePercent": { "default": 0.5, "type": "number", "minimum": 0 }, "includeSchedule": { "default": false, "type": "boolean" } }, "required": [ "homePrice", "downPayment", "interestRate", "loanTermYears" ], "additionalProperties": false }, "example": { "homePrice": 350000, "downPayment": 70000, "interestRate": 6.74, "loanTermYears": 30, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "monthlyHOA": 0, "includePMI": true } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number", "description": "Home price minus down payment ($)" }, "downPaymentPercent": { "type": "number", "description": "Down payment as a percent of home price" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest payment ($)" }, "monthlyPropertyTax": { "type": "number", "description": "Monthly property tax ($)" }, "monthlyInsurance": { "type": "number", "description": "Monthly home insurance ($)" }, "monthlyPMI": { "type": "number", "description": "Monthly PMI ($); 0 when not required" }, "monthlyHOA": { "type": "number", "description": "Monthly HOA fees ($)" }, "totalMonthlyPayment": { "type": "number", "description": "Sum of all monthly payment components ($)" }, "totalInterest": { "type": "number", "description": "Total interest paid over the full loan term ($)" }, "numberOfPayments": { "type": "number", "description": "Total number of monthly payments" } }, "required": [ "loanAmount", "downPaymentPercent", "monthlyPI", "monthlyPropertyTax", "monthlyInsurance", "monthlyPMI", "monthlyHOA", "totalMonthlyPayment", "totalInterest", "numberOfPayments" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/pmi": { "post": { "operationId": "calculate_pmi", "summary": "Calculate PMI", "description": "Calculates monthly PMI cost, LTV ratio, and estimated PMI removal timeline accounting for principal paydown and home appreciation.", "tags": [ "mortgage", "insurance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "pmiRatePercent": { "default": 0.5, "type": "number", "minimum": 0 }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "monthlyHOA": { "default": 0, "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "default": 3, "type": "number", "minimum": 0 } }, "required": [ "homePrice", "downPayment", "interestRate", "loanTermYears" ], "additionalProperties": false }, "example": { "homePrice": 350000, "downPayment": 35000, "interestRate": 6.74, "loanTermYears": 30, "pmiRatePercent": 0.5, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "monthlyHOA": 0, "annualAppreciationPercent": 3 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number", "description": "Home price minus down payment ($)" }, "downPaymentPercent": { "type": "number", "description": "Down payment as a percent of home price" }, "loanToValue": { "type": "number", "description": "Loan amount as a percent of home price" }, "requiresPMI": { "type": "boolean", "description": "True when down payment is below 20%" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest payment ($)" }, "monthlyPMI": { "type": "number", "description": "Monthly PMI ($); 0 when not required" }, "annualPMI": { "type": "number", "description": "Annual PMI cost ($); 0 when not required" }, "monthlyPropertyTax": { "type": "number", "description": "Monthly property tax ($)" }, "monthlyInsurance": { "type": "number", "description": "Monthly home insurance ($)" }, "monthlyHOA": { "type": "number", "description": "Monthly HOA fees ($)" }, "totalMonthlyWithPMI": { "type": "number", "description": "Total monthly payment including PMI ($)" }, "totalMonthlyWithoutPMI": { "type": "number", "description": "Total monthly payment after PMI removal ($)" }, "requiredEquityFor80LTV": { "type": "number", "description": "Equity required to reach 80% LTV ($)" }, "currentEquity": { "type": "number", "description": "Current equity at purchase (= down payment) ($)" }, "additionalEquityNeeded": { "type": "number", "description": "Additional equity needed to reach 80% LTV ($)" }, "pmiRemovalMonths": { "type": "number", "description": "Month when LTV first reaches 80% (0 if PMI not required)" }, "pmiRemovalYears": { "type": "number", "description": "pmiRemovalMonths / 12 as a decimal" }, "totalPMICost": { "type": "number", "description": "Total PMI premiums until removal ($)" } }, "required": [ "loanAmount", "downPaymentPercent", "loanToValue", "requiresPMI", "monthlyPI", "monthlyPMI", "annualPMI", "monthlyPropertyTax", "monthlyInsurance", "monthlyHOA", "totalMonthlyWithPMI", "totalMonthlyWithoutPMI", "requiredEquityFor80LTV", "currentEquity", "additionalEquityNeeded", "pmiRemovalMonths", "pmiRemovalYears", "totalPMICost" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/refinance": { "post": { "operationId": "analyze_refinance", "summary": "Analyse refinance scenario", "description": "Analyses a mortgage refinance scenario by comparing the current loan to a proposed refinance. Returns monthly savings, break-even period (months/years to recover closing costs), lifetime cost comparison, and a should-refinance heuristic. Supports rate-and-term and cash-out refinances.", "tags": [ "refinance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentBalance": { "type": "number", "minimum": 0 }, "currentRate": { "type": "number", "minimum": 0 }, "currentMonthlyPayment": { "type": "number", "minimum": 0 }, "remainingYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "newRate": { "type": "number", "minimum": 0 }, "newTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "cashOutAmount": { "default": 0, "type": "number", "minimum": 0 }, "propertyValue": { "default": 0, "type": "number", "minimum": 0 }, "rollClosingCosts": { "default": false, "type": "boolean" } }, "required": [ "currentBalance", "currentRate", "currentMonthlyPayment", "remainingYears", "newRate", "newTermYears" ], "additionalProperties": false }, "example": { "currentBalance": 320000, "currentRate": 7, "currentMonthlyPayment": 2129, "remainingYears": 27, "newRate": 6.74, "newTermYears": 30, "closingCosts": 5600, "cashOutAmount": 40000, "propertyValue": 400000, "rollClosingCosts": false } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "newLoanAmount": { "type": "number", "description": "New loan balance after adding cash-out (and closing costs if rolled) ($)" }, "newMonthlyPayment": { "type": "number", "description": "New loan monthly principal & interest payment ($)" }, "monthlySavings": { "type": "number", "description": "Monthly payment reduction: current − new ($). Negative = payment increases." }, "annualSavings": { "type": "number", "description": "monthlySavings × 12 ($)" }, "savingsAtFiveYears": { "type": "number", "description": "Net benefit after 5 years: (monthlySavings × 60) − closingCosts ($)" }, "breakEvenMonths": { "type": "number", "description": "Months to recover closing costs through monthly savings. 0 when no savings." }, "breakEvenYears": { "type": "number", "description": "breakEvenMonths / 12" }, "currentTotalInterest": { "type": "number", "description": "Remaining interest on the current loan ($)" }, "currentTotalCost": { "type": "number", "description": "Total remaining cost of current loan (balance + interest) ($)" }, "newTotalInterest": { "type": "number", "description": "Total interest on new loan ($)" }, "newTotalCost": { "type": "number", "description": "Total cost of new loan including closing costs ($)" }, "lifetimeDifference": { "type": "number", "description": "currentTotalCost − newTotalCost ($). Positive = refinancing saves money long-term." }, "loanToValue": { "type": "number", "description": "New loan-to-value ratio (%). 0 when propertyValue was not provided." }, "equityRemaining": { "type": "number", "description": "Equity remaining after refinance ($). 0 when propertyValue was not provided." }, "shouldRefinance": { "type": "boolean", "description": "Simple heuristic: true when monthlySavings > 0 and breakEvenYears < 5." } }, "required": [ "newLoanAmount", "newMonthlyPayment", "monthlySavings", "annualSavings", "savingsAtFiveYears", "breakEvenMonths", "breakEvenYears", "currentTotalInterest", "currentTotalCost", "newTotalInterest", "newTotalCost", "lifetimeDifference", "loanToValue", "equityRemaining", "shouldRefinance" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/cash-out": { "post": { "operationId": "analyze_cash_out_refinance", "summary": "Model cash-out refinance", "description": "Educational modeled cash-out refinance: equity withdrawn, estimatedNetCashToBorrower with cashReceivedBasis, LTV, equity remaining, paymentChangeDirection, crossesEightyPercentLtv, optional estimatedMonthlyPmi when LTV ≥ 80%. Not loan approval, live rates, tax advice, or debt-consolidation guidance.", "tags": [ "refinance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentBalance": { "type": "number", "minimum": 0 }, "currentRate": { "type": "number", "minimum": 0 }, "currentMonthlyPayment": { "type": "number", "minimum": 0 }, "remainingYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "newRate": { "type": "number", "minimum": 0 }, "newTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "cashOutAmount": { "type": "number", "minimum": 1 }, "propertyValue": { "type": "number", "minimum": 1 }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "rollClosingCosts": { "default": false, "type": "boolean" }, "pmiRatePercent": { "type": "number", "minimum": 0 }, "propertyTaxRate": { "type": "number", "minimum": 0 }, "annualHomeInsurance": { "type": "number", "minimum": 0 } }, "required": [ "currentBalance", "currentRate", "currentMonthlyPayment", "remainingYears", "newRate", "newTermYears", "cashOutAmount", "propertyValue" ], "additionalProperties": false }, "example": { "currentBalance": 280000, "currentRate": 7, "currentMonthlyPayment": 1863, "remainingYears": 27, "newRate": 6.74, "newTermYears": 30, "cashOutAmount": 40000, "propertyValue": 400000, "closingCosts": 5600, "rollClosingCosts": false } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "monthlySavingsBasis": { "type": "string", "const": "pi_only" }, "cashReceivedBasis": { "type": "string", "enum": [ "gross_cash_out", "net_after_closing_costs", "rolled_closing_costs" ] }, "paymentChangeDirection": { "type": "string", "enum": [ "increase", "decrease", "flat" ] }, "hasPositiveSavings": { "type": "boolean" }, "negativeSavingsReason": { "anyOf": [ { "type": "string", "enum": [ "higher_payment", "higher_rate", "shorter_term", "rolled_costs", "cash_out_amount" ] }, { "type": "null" } ] }, "assistantHeadline": { "type": "string" }, "cashOutAmount": { "type": "number" }, "estimatedNetCashToBorrower": { "type": "number" }, "priorLoanBalance": { "type": "number" }, "newLoanAmount": { "type": "number" }, "priorLoanToValuePercent": { "type": "number" }, "loanToValuePercent": { "type": "number" }, "crossesEightyPercentLtv": { "type": "boolean" }, "highPostRefinanceLtv": { "type": "boolean" }, "equityBeforeRefinance": { "type": "number" }, "equityRemaining": { "type": "number" }, "equityUsedForCashOut": { "type": "number" }, "equityExtractionPercent": { "type": "number" }, "newMonthlyPayment": { "type": "number" }, "monthlySavings": { "type": "number" }, "monthlyPaymentChange": { "type": "number" }, "annualSavings": { "type": "number" }, "breakEvenMonths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "breakEvenYears": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "closingCosts": { "type": "number" }, "savingsAtFiveYears": { "type": "number" }, "currentTotalInterest": { "type": "number" }, "newTotalInterest": { "type": "number" }, "modeledInterestSavings": { "type": "number" }, "modeledLifetimeCostDifference": { "type": "number" }, "estimatedMonthlyPmi": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Educational PMI estimate when LTV ≥ 80%; null otherwise" } }, "required": [ "monthlySavingsBasis", "cashReceivedBasis", "paymentChangeDirection", "hasPositiveSavings", "negativeSavingsReason", "assistantHeadline", "cashOutAmount", "estimatedNetCashToBorrower", "priorLoanBalance", "newLoanAmount", "priorLoanToValuePercent", "loanToValuePercent", "crossesEightyPercentLtv", "highPostRefinanceLtv", "equityBeforeRefinance", "equityRemaining", "equityUsedForCashOut", "equityExtractionPercent", "newMonthlyPayment", "monthlySavings", "monthlyPaymentChange", "annualSavings", "breakEvenMonths", "breakEvenYears", "closingCosts", "savingsAtFiveYears", "currentTotalInterest", "newTotalInterest", "modeledInterestSavings", "modeledLifetimeCostDifference", "estimatedMonthlyPmi" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/break-even": { "post": { "operationId": "analyze_break_even", "summary": "Refinance break-even analysis", "description": "Educational refinance break-even: months to recover user-entered closing costs (and optional prepayment penalty) through modeled monthly P&I savings (monthlySavingsBasis: pi_only). Returns nullable break-even when savings are not positive, adjusted break-even with penalty, and modeled interest/cost differences. Not loan approval, live rates, or tax advice.", "tags": [ "refinance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentBalance": { "type": "number", "minimum": 0 }, "currentRate": { "type": "number", "minimum": 0 }, "currentMonthlyPayment": { "type": "number", "minimum": 0 }, "remainingYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "newRate": { "type": "number", "minimum": 0 }, "newTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "rollClosingCosts": { "default": false, "type": "boolean" }, "prepaymentPenaltyAmount": { "default": 0, "type": "number", "minimum": 0 }, "expectedStayMonths": { "default": 60, "type": "integer", "minimum": 0, "maximum": 600, "format": "int32" } }, "required": [ "currentBalance", "currentRate", "currentMonthlyPayment", "remainingYears", "newRate", "newTermYears" ], "additionalProperties": false }, "example": { "currentBalance": 280000, "currentRate": 7, "currentMonthlyPayment": 1863, "remainingYears": 27, "newRate": 6, "newTermYears": 30, "closingCosts": 5600, "rollClosingCosts": false, "prepaymentPenaltyAmount": 0, "expectedStayMonths": 60 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "monthlySavingsBasis": { "type": "string", "const": "pi_only" }, "hasPositiveSavings": { "type": "boolean" }, "negativeSavingsReason": { "anyOf": [ { "type": "string", "enum": [ "higher_payment", "higher_rate", "shorter_term", "rolled_costs" ] }, { "type": "null" } ] }, "assistantHeadline": { "type": "string" }, "newLoanAmount": { "type": "number" }, "newMonthlyPayment": { "type": "number" }, "monthlySavings": { "type": "number" }, "annualSavings": { "type": "number" }, "breakEvenMonths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "breakEvenYears": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "effectiveClosingCosts": { "type": "number" }, "prepaymentPenaltyAmount": { "type": "number" }, "adjustedBreakEvenMonths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "adjustedBreakEvenYears": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currentTotalInterest": { "type": "number" }, "newTotalInterest": { "type": "number" }, "modeledInterestSavings": { "type": "number" }, "modeledLifetimeCostDifference": { "type": "number" }, "savingsAtFiveYears": { "type": "number" }, "cumulativeSavingsAtStay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recoupsCostsBeforeStay": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "monthlySavingsBasis", "hasPositiveSavings", "negativeSavingsReason", "assistantHeadline", "newLoanAmount", "newMonthlyPayment", "monthlySavings", "annualSavings", "breakEvenMonths", "breakEvenYears", "effectiveClosingCosts", "prepaymentPenaltyAmount", "adjustedBreakEvenMonths", "adjustedBreakEvenYears", "currentTotalInterest", "newTotalInterest", "modeledInterestSavings", "modeledLifetimeCostDifference", "savingsAtFiveYears", "cumulativeSavingsAtStay", "recoupsCostsBeforeStay" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/loan-comparison": { "post": { "operationId": "compare_loans", "summary": "Compare two loan options", "description": "Compares two mortgage loan options (Loan A vs Loan B) on the same property. Returns monthly payment, total interest, upfront costs, and total lifetime cost for each loan, plus monthly, upfront, and lifetime cost differences. Identifies which loan has the lower lifetime cost.", "tags": [ "comparison" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "interestRateA": { "type": "number", "minimum": 0 }, "loanTermYearsA": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "pointsA": { "default": 0, "type": "number", "minimum": 0 }, "closingCostsA": { "default": 0, "type": "number", "minimum": 0 }, "interestRateB": { "type": "number", "minimum": 0 }, "loanTermYearsB": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "pointsB": { "default": 0, "type": "number", "minimum": 0 }, "closingCostsB": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "homePrice", "downPayment", "interestRateA", "loanTermYearsA", "interestRateB", "loanTermYearsB" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "interestRateA": 6.74, "loanTermYearsA": 30, "pointsA": 0, "closingCostsA": 5000, "interestRateB": 6, "loanTermYearsB": 30, "pointsB": 1, "closingCostsB": 6000 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number", "description": "homePrice − downPayment ($)" }, "monthlyTax": { "type": "number", "description": "Monthly property tax shared by both loans ($)" }, "monthlyInsurance": { "type": "number", "description": "Monthly home insurance shared by both loans ($)" }, "monthlyPMI": { "type": "number", "description": "Monthly PMI shared by both loans (0 if down ≥ 20%) ($)" }, "monthlyPIA": { "type": "number", "description": "Monthly P&I for Loan A ($)" }, "totalInterestA": { "type": "number", "description": "Total interest paid over Loan A term ($)" }, "pointsCostA": { "type": "number", "description": "Upfront cost of points for Loan A ($)" }, "upfrontCostA": { "type": "number", "description": "Total upfront cost for Loan A: closing costs + points ($)" }, "totalCostA": { "type": "number", "description": "Total economic cost for Loan A: all P&I + upfront costs ($)" }, "totalMonthlyA": { "type": "number", "description": "Total monthly payment for Loan A including shared costs ($)" }, "monthlyPIB": { "type": "number", "description": "Monthly P&I for Loan B ($)" }, "totalInterestB": { "type": "number", "description": "Total interest paid over Loan B term ($)" }, "pointsCostB": { "type": "number", "description": "Upfront cost of points for Loan B ($)" }, "upfrontCostB": { "type": "number", "description": "Total upfront cost for Loan B ($)" }, "totalCostB": { "type": "number", "description": "Total economic cost for Loan B ($)" }, "totalMonthlyB": { "type": "number", "description": "Total monthly payment for Loan B ($)" }, "monthlyDifference": { "type": "number", "description": "totalMonthlyA − totalMonthlyB. Positive = Loan B cheaper monthly." }, "upfrontDifference": { "type": "number", "description": "upfrontCostA − upfrontCostB. Positive = Loan B cheaper upfront." }, "lifetimeDifference": { "type": "number", "description": "totalCostA − totalCostB. Positive = Loan B cheaper long-term." }, "lowerLifetimeCost": { "type": "string", "enum": [ "A", "B", "equal" ], "description": "Which loan has the lower total lifetime cost" } }, "required": [ "loanAmount", "monthlyTax", "monthlyInsurance", "monthlyPMI", "monthlyPIA", "totalInterestA", "pointsCostA", "upfrontCostA", "totalCostA", "totalMonthlyA", "monthlyPIB", "totalInterestB", "pointsCostB", "upfrontCostB", "totalCostB", "totalMonthlyB", "monthlyDifference", "upfrontDifference", "lifetimeDifference", "lowerLifetimeCost" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/affordability": { "post": { "operationId": "estimate_affordability", "summary": "Estimate home affordability", "description": "Estimates the maximum home price a buyer can afford based on income, debts, down payment, and expected mortgage rate. Applies the standard 28/43 DTI rule. Returns max home price, required down payment, cash needed at closing, estimated monthly payment breakdown, and DTI ratios with the binding constraint.", "tags": [ "affordability" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "annualIncome": { "type": "number", "minimum": 0 }, "monthlyDebts": { "default": 0, "type": "number", "minimum": 0 }, "downPaymentPercent": { "default": 20, "type": "number", "minimum": 0, "maximum": 100 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "monthlyHOA": { "default": 0, "type": "number", "minimum": 0 }, "targetFrontEndDTI": { "default": 28, "type": "number", "minimum": 1, "maximum": 50 } }, "required": [ "annualIncome", "interestRate" ], "additionalProperties": false }, "example": { "annualIncome": 120000, "monthlyDebts": 800, "downPaymentPercent": 20, "interestRate": 6.74, "loanTermYears": 30, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "monthlyHOA": 0, "targetFrontEndDTI": 28 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "maxHomePrice": { "type": "number", "description": "Maximum affordable home price ($)" }, "maxLoanAmount": { "type": "number", "description": "Maximum loan amount ($)" }, "requiredDownPayment": { "type": "number", "description": "Required down payment amount ($)" }, "estimatedClosingCosts": { "type": "number", "description": "Estimated closing costs at 3% of home price ($)" }, "totalCashNeeded": { "type": "number", "description": "Total cash needed at closing: down payment + closing costs ($)" }, "monthlyIncome": { "type": "number", "description": "Monthly income (annualIncome / 12) ($)" }, "monthlyPI": { "type": "number", "description": "Monthly principal & interest at max home price ($)" }, "monthlyPropertyTax": { "type": "number", "description": "Monthly property tax ($)" }, "monthlyInsurance": { "type": "number", "description": "Monthly homeowners insurance ($)" }, "monthlyPMI": { "type": "number", "description": "Monthly PMI (0 when down payment ≥ 20%) ($)" }, "totalMonthlyPayment": { "type": "number", "description": "Total monthly payment: PITI + HOA ($)" }, "frontEndDTI": { "type": "number", "description": "Housing payment / monthly income × 100 (%)" }, "backEndDTI": { "type": "number", "description": "(Housing + all debts) / monthly income × 100 (%)" }, "qualifies": { "type": "boolean", "description": "true when frontEndDTI ≤ 28 and backEndDTI ≤ 43" }, "maxFrontEndPayment": { "type": "number", "description": "Monthly payment ceiling from front-end DTI target ($)" }, "maxBackEndPayment": { "type": "number", "description": "Monthly payment ceiling from back-end 43% rule ($)" }, "maxMonthlyPayment": { "type": "number", "description": "Binding monthly limit used: min(maxFrontEndPayment, maxBackEndPayment) ($)" }, "constrainedBy": { "type": "string", "enum": [ "frontEnd", "backEnd" ], "description": "Which DTI constraint is binding" } }, "required": [ "maxHomePrice", "maxLoanAmount", "requiredDownPayment", "estimatedClosingCosts", "totalCashNeeded", "monthlyIncome", "monthlyPI", "monthlyPropertyTax", "monthlyInsurance", "monthlyPMI", "totalMonthlyPayment", "frontEndDTI", "backEndDTI", "qualifies", "maxFrontEndPayment", "maxBackEndPayment", "maxMonthlyPayment", "constrainedBy" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/buydown": { "post": { "operationId": "analyze_buydown", "summary": "Analyse temporary buydown", "description": "Educational temporary buydown analysis (2-1, 1-0, or custom). Returns qualifying payment, year-by-year temporary payment reductions, monthly savings, payment shock at reset, and estimated buydown fund. P&I only.", "tags": [ "mortgage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "noteRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "buydownType": { "default": "2-1", "type": "string", "enum": [ "2-1", "1-0", "custom" ] }, "customYear1Reduction": { "default": 2, "type": "number", "minimum": 0 }, "customYear2Reduction": { "default": 1, "type": "number", "minimum": 0 }, "customYear3Reduction": { "default": 0, "type": "number", "minimum": 0 }, "quotedBuydownCost": { "default": 0, "type": "number", "minimum": 0 }, "includeSchedule": { "default": false, "type": "boolean" } }, "required": [ "homePrice", "downPayment", "noteRate", "loanTermYears" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "noteRate": 6.74, "loanTermYears": 30, "buydownType": "2-1", "customYear1Reduction": 2, "customYear2Reduction": 1, "customYear3Reduction": 0, "quotedBuydownCost": 0 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "noteRate": { "type": "number" }, "buydownType": { "type": "string", "enum": [ "2-1", "1-0", "custom" ] }, "qualifyingPayment": { "type": "number" }, "steadyStateMonthlyPI": { "type": "number" }, "year1EffectiveRate": { "type": "number" }, "year1MonthlyPI": { "type": "number" }, "year2EffectiveRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year2MonthlyPI": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year3EffectiveRate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year3MonthlyPI": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthlySavingsYear1": { "type": "number" }, "monthlySavingsYear2": { "type": "number" }, "paymentShockAtReset": { "type": "number" }, "subsidizedYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "estimatedBuydownFund": { "type": "number" }, "cumulativePaymentSavings": { "type": "number" }, "savingsFirst12Months": { "type": "number" }, "savingsFirst24Months": { "type": "number" }, "quotedBuydownCost": { "type": "number" }, "fundVsQuoteDifference": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "isQuoteBelowEstimate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "totalPIBaseline": { "type": "number" }, "totalPIWithBuydown": { "type": "number" }, "baselineSchedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } }, "buydownPaymentSchedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } } }, "required": [ "loanAmount", "noteRate", "buydownType", "qualifyingPayment", "steadyStateMonthlyPI", "year1EffectiveRate", "year1MonthlyPI", "year2EffectiveRate", "year2MonthlyPI", "year3EffectiveRate", "year3MonthlyPI", "monthlySavingsYear1", "monthlySavingsYear2", "paymentShockAtReset", "subsidizedYears", "estimatedBuydownFund", "cumulativePaymentSavings", "savingsFirst12Months", "savingsFirst24Months", "quotedBuydownCost", "fundVsQuoteDifference", "isQuoteBelowEstimate", "totalPIBaseline", "totalPIWithBuydown" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/apr": { "post": { "operationId": "calculate_apr", "summary": "Calculate APR (educational estimate)", "description": "Calculates an educational actuarial APR for a fixed-rate mortgage from the note rate, loan amount, and upfront finance charges (points, origination, additional finance charges). Returns APR, note rate, amount financed, fee breakdown, isAprHigherThanNoteRate, and aprDifferenceDollars vs a no-fee baseline.", "tags": [ "mortgage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "noteRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "pointsPercent": { "default": 0, "type": "number", "minimum": 0 }, "originationFee": { "default": 0, "type": "number", "minimum": 0 }, "additionalFinanceCharges": { "default": 0, "type": "number", "minimum": 0 }, "includeSchedule": { "default": false, "type": "boolean" } }, "required": [ "homePrice", "downPayment", "noteRate", "loanTermYears" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "noteRate": 6.74, "loanTermYears": 30, "pointsPercent": 0, "originationFee": 0, "additionalFinanceCharges": 0 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "noteRate": { "type": "number" }, "monthlyPI": { "type": "number" }, "pointsCost": { "type": "number" }, "originationFee": { "type": "number" }, "additionalFinanceCharges": { "type": "number" }, "totalFinanceCharges": { "type": "number" }, "amountFinanced": { "type": "number" }, "apr": { "type": "number" }, "aprSpread": { "type": "number" }, "isAprHigherThanNoteRate": { "type": "boolean" }, "aprDifferenceDollars": { "type": "number" }, "totalInterest": { "type": "number" }, "totalOfPayments": { "type": "number" }, "financeCharge": { "type": "number" }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } } }, "required": [ "loanAmount", "noteRate", "monthlyPI", "pointsCost", "originationFee", "additionalFinanceCharges", "totalFinanceCharges", "amountFinanced", "apr", "aprSpread", "isAprHigherThanNoteRate", "aprDifferenceDollars", "totalInterest", "totalOfPayments", "financeCharge" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/15-vs-30-year": { "post": { "operationId": "compare_15_vs_30_year", "summary": "Compare 15-year vs 30-year mortgages", "description": "Compares 15-year and 30-year fixed loans on the same loan amount with separate user-supplied rates. Returns monthly P&I, total interest, principal and equity through expected ownership, payoff dates, interest saved with 15-year term, and months until interest savings exceed extra 15-year payments.", "tags": [ "comparison" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "interestRate15Year": { "type": "number", "minimum": 0 }, "interestRate30Year": { "type": "number", "minimum": 0 }, "expectedOwnershipYears": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "monthlyGrossIncome": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "homePrice", "downPayment", "interestRate15Year", "interestRate30Year" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "interestRate15Year": 6, "interestRate30Year": 6.74, "expectedOwnershipYears": 10 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "programALabel": { "type": "string", "const": "15-Year" }, "programBLabel": { "type": "string", "const": "30-Year" }, "loanAmount": { "type": "number" }, "downPaymentPercent": { "type": "number" }, "expectedOwnershipYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "expectedOwnershipMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "programA": { "type": "object", "properties": { "termYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interestRate": { "type": "number" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest ($)" }, "payoffMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payoffDate": { "type": "string", "description": "Illustrative payoff date (ISO YYYY-MM-DD)" }, "totalInterestFullTerm": { "type": "number" }, "totalPrincipalPaidFullTerm": { "type": "number" }, "totalPIFullTerm": { "type": "number" }, "totalInterestThroughOwnership": { "type": "number", "description": "Interest paid through expected ownership period ($)" }, "totalPrincipalPaidThroughOwnership": { "type": "number", "description": "Principal paid through expected ownership period ($)" }, "totalPIThroughOwnership": { "type": "number" }, "remainingBalanceAfterOwnership": { "type": "number", "description": "Loan balance after ownership period ($)" }, "equityBuiltAfterOwnership": { "type": "number", "description": "loanAmount − remainingBalanceAfterOwnership ($)" } }, "required": [ "termYears", "interestRate", "monthlyPI", "payoffMonths", "payoffDate", "totalInterestFullTerm", "totalPrincipalPaidFullTerm", "totalPIFullTerm", "totalInterestThroughOwnership", "totalPrincipalPaidThroughOwnership", "totalPIThroughOwnership", "remainingBalanceAfterOwnership", "equityBuiltAfterOwnership" ], "additionalProperties": false, "description": "15-year fixed program" }, "programB": { "type": "object", "properties": { "termYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "interestRate": { "type": "number" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest ($)" }, "payoffMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payoffDate": { "type": "string", "description": "Illustrative payoff date (ISO YYYY-MM-DD)" }, "totalInterestFullTerm": { "type": "number" }, "totalPrincipalPaidFullTerm": { "type": "number" }, "totalPIFullTerm": { "type": "number" }, "totalInterestThroughOwnership": { "type": "number", "description": "Interest paid through expected ownership period ($)" }, "totalPrincipalPaidThroughOwnership": { "type": "number", "description": "Principal paid through expected ownership period ($)" }, "totalPIThroughOwnership": { "type": "number" }, "remainingBalanceAfterOwnership": { "type": "number", "description": "Loan balance after ownership period ($)" }, "equityBuiltAfterOwnership": { "type": "number", "description": "loanAmount − remainingBalanceAfterOwnership ($)" } }, "required": [ "termYears", "interestRate", "monthlyPI", "payoffMonths", "payoffDate", "totalInterestFullTerm", "totalPrincipalPaidFullTerm", "totalPIFullTerm", "totalInterestThroughOwnership", "totalPrincipalPaidThroughOwnership", "totalPIThroughOwnership", "remainingBalanceAfterOwnership", "equityBuiltAfterOwnership" ], "additionalProperties": false, "description": "30-year fixed program" }, "monthlyPIDifference": { "type": "number", "description": "15-year minus 30-year monthly P&I ($)" }, "extraMonthlyCostWith15Year": { "type": "number" }, "totalInterestDifferenceFullTerm": { "type": "number" }, "interestSavedWith15Year": { "type": "number" }, "totalInterestDifferenceThroughOwnership": { "type": "number" }, "totalPrincipalPaidDifferenceThroughOwnership": { "type": "number" }, "totalPIDifferenceThroughOwnership": { "type": "number" }, "payoffMonthsDifference": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "yearsFasterWith15Year": { "type": "number" }, "equityBuiltAfterOwnership15Year": { "type": "number" }, "equityBuiltAfterOwnership30Year": { "type": "number" }, "additionalEquityBuiltWith15Year": { "type": "number" }, "lowerMonthlyPI": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "lowerTotalInterestFullTerm": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "lowerTotalInterestThroughOwnership": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "monthsUntilInterestSavingsExceedExtraPayments": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthlyPI15AsPercentOfIncome": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthlyPI30AsPercentOfIncome": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "paymentStressDifferencePoints": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "exceeds28PercentGuideline15Year": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "exceeds28PercentGuideline30Year": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "programALabel", "programBLabel", "loanAmount", "downPaymentPercent", "expectedOwnershipYears", "expectedOwnershipMonths", "programA", "programB", "monthlyPIDifference", "extraMonthlyCostWith15Year", "totalInterestDifferenceFullTerm", "interestSavedWith15Year", "totalInterestDifferenceThroughOwnership", "totalPrincipalPaidDifferenceThroughOwnership", "totalPIDifferenceThroughOwnership", "payoffMonthsDifference", "yearsFasterWith15Year", "equityBuiltAfterOwnership15Year", "equityBuiltAfterOwnership30Year", "additionalEquityBuiltWith15Year", "lowerMonthlyPI", "lowerTotalInterestFullTerm", "lowerTotalInterestThroughOwnership", "monthsUntilInterestSavingsExceedExtraPayments", "monthlyPI15AsPercentOfIncome", "monthlyPI30AsPercentOfIncome", "paymentStressDifferencePoints", "exceeds28PercentGuideline15Year", "exceeds28PercentGuideline30Year" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/fha-vs-conventional": { "post": { "operationId": "compare_fha_vs_conventional", "summary": "Compare FHA vs conventional loans", "description": "Compares FHA and conventional loans on the same property and down payment. Returns monthly loan payments, total monthly housing, upfront cash, estimated loan cost over expected ownership years, break-even ownership years, and conventional PMI end estimate. User-supplied MIP/PMI assumptions.", "tags": [ "comparison" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "monthlyHOA": { "default": 0, "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "expectedOwnershipYears": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "fhaInterestRate": { "type": "number", "minimum": 0 }, "fhaUfmipPercent": { "default": 1.75, "type": "number", "minimum": 0 }, "financeUfmipIntoLoan": { "default": true, "description": "Whether UFMIP is financed into the FHA loan balance", "type": "boolean" }, "fhaAnnualMipRatePercent": { "default": 0.55, "type": "number", "minimum": 0 }, "fhaMipDurationMode": { "default": "life_of_loan", "type": "string", "enum": [ "life_of_loan", "eleven_years", "custom_months" ] }, "fhaMipCustomMonths": { "default": 132, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "format": "int32" }, "fhaClosingCosts": { "default": 5000, "type": "number", "minimum": 0 }, "fhaPointsPercent": { "default": 0, "type": "number", "minimum": 0 }, "conventionalInterestRate": { "type": "number", "minimum": 0 }, "conventionalPmiRatePercent": { "default": 0.5, "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "default": 3, "type": "number", "minimum": 0 }, "conventionalClosingCosts": { "default": 5000, "type": "number", "minimum": 0 }, "conventionalPointsPercent": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "homePrice", "downPayment", "fhaInterestRate", "conventionalInterestRate" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 14000, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "expectedOwnershipYears": 10, "fhaInterestRate": 6.25, "conventionalInterestRate": 6.74, "fhaAnnualMipRatePercent": 0.55, "conventionalPmiRatePercent": 0.5 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "programALabel": { "type": "string", "const": "FHA" }, "programBLabel": { "type": "string", "const": "Conventional" }, "baseLoanAmount": { "type": "number" }, "downPaymentPercent": { "type": "number" }, "expectedOwnershipYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "expectedOwnershipMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "sharedHousing": { "type": "object", "properties": { "monthlyPropertyTax": { "type": "number" }, "monthlyInsurance": { "type": "number" }, "monthlyHOA": { "type": "number" } }, "required": [ "monthlyPropertyTax", "monthlyInsurance", "monthlyHOA" ], "additionalProperties": false }, "programA": { "type": "object", "properties": { "loanAmount": { "type": "number", "description": "Loan amount used for amortization ($)" }, "upfrontMortgageInsurance": { "type": "number", "description": "Upfront mortgage insurance amount (UFMIP for FHA; 0 for conventional) ($)" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest ($)" }, "monthlyMortgageInsurance": { "type": "number", "description": "Monthly MIP or PMI ($)" }, "monthlyLoanPayment": { "type": "number", "description": "Monthly P&I plus mortgage insurance ($)" }, "pointsCost": { "type": "number", "description": "Upfront points cost ($)" }, "upfrontCash": { "type": "number", "description": "Cash due at closing: closing costs, points, and cash UFMIP ($)" }, "totalPIThroughOwnership": { "type": "number", "description": "Total P&I paid through expected ownership period ($)" }, "totalMortgageInsuranceThroughOwnership": { "type": "number", "description": "Total MIP/PMI paid through expected ownership period ($)" }, "totalInterestThroughOwnership": { "type": "number", "description": "Total interest paid through expected ownership period ($)" }, "estimatedLoanCostOverOwnershipPeriod": { "type": "number", "description": "Estimated loan cost over ownership period: P&I + mortgage insurance + upfront cash ($)" } }, "required": [ "loanAmount", "upfrontMortgageInsurance", "monthlyPI", "monthlyMortgageInsurance", "monthlyLoanPayment", "pointsCost", "upfrontCash", "totalPIThroughOwnership", "totalMortgageInsuranceThroughOwnership", "totalInterestThroughOwnership", "estimatedLoanCostOverOwnershipPeriod" ], "additionalProperties": false, "description": "FHA loan economics" }, "programB": { "type": "object", "properties": { "loanAmount": { "type": "number", "description": "Loan amount used for amortization ($)" }, "upfrontMortgageInsurance": { "type": "number", "description": "Upfront mortgage insurance amount (UFMIP for FHA; 0 for conventional) ($)" }, "monthlyPI": { "type": "number", "description": "Monthly principal and interest ($)" }, "monthlyMortgageInsurance": { "type": "number", "description": "Monthly MIP or PMI ($)" }, "monthlyLoanPayment": { "type": "number", "description": "Monthly P&I plus mortgage insurance ($)" }, "pointsCost": { "type": "number", "description": "Upfront points cost ($)" }, "upfrontCash": { "type": "number", "description": "Cash due at closing: closing costs, points, and cash UFMIP ($)" }, "totalPIThroughOwnership": { "type": "number", "description": "Total P&I paid through expected ownership period ($)" }, "totalMortgageInsuranceThroughOwnership": { "type": "number", "description": "Total MIP/PMI paid through expected ownership period ($)" }, "totalInterestThroughOwnership": { "type": "number", "description": "Total interest paid through expected ownership period ($)" }, "estimatedLoanCostOverOwnershipPeriod": { "type": "number", "description": "Estimated loan cost over ownership period: P&I + mortgage insurance + upfront cash ($)" } }, "required": [ "loanAmount", "upfrontMortgageInsurance", "monthlyPI", "monthlyMortgageInsurance", "monthlyLoanPayment", "pointsCost", "upfrontCash", "totalPIThroughOwnership", "totalMortgageInsuranceThroughOwnership", "totalInterestThroughOwnership", "estimatedLoanCostOverOwnershipPeriod" ], "additionalProperties": false, "description": "Conventional loan economics" }, "programAHousing": { "type": "object", "properties": { "monthlyPropertyTax": { "type": "number" }, "monthlyInsurance": { "type": "number" }, "monthlyHOA": { "type": "number" }, "totalMonthlyHousing": { "type": "number", "description": "Monthly loan payment plus tax, insurance, and HOA ($)" } }, "required": [ "monthlyPropertyTax", "monthlyInsurance", "monthlyHOA", "totalMonthlyHousing" ], "additionalProperties": false }, "programBHousing": { "type": "object", "properties": { "monthlyPropertyTax": { "type": "number" }, "monthlyInsurance": { "type": "number" }, "monthlyHOA": { "type": "number" }, "totalMonthlyHousing": { "type": "number", "description": "Monthly loan payment plus tax, insurance, and HOA ($)" } }, "required": [ "monthlyPropertyTax", "monthlyInsurance", "monthlyHOA", "totalMonthlyHousing" ], "additionalProperties": false }, "monthlyHousingDifference": { "type": "number", "description": "FHA minus conventional total monthly housing (includes escrow)" }, "lifetimeLoanCostDifference": { "type": "number", "description": "FHA minus conventional estimated loan cost over ownership period (loan economics only)" }, "upfrontDifference": { "type": "number", "description": "FHA minus conventional upfront cash ($)" }, "monthlyLoanPaymentDifference": { "type": "number", "description": "FHA minus conventional monthly loan payment ($)" }, "lowerMonthlyLoanPayment": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "lowerLoanCostOverOwnershipPeriod": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "breakEvenOwnershipYears": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated years of ownership when cumulative loan-only costs intersect; null if no cross within loan term" }, "conventionalPmiEndsAfterYears": { "type": "number", "description": "Estimated years until conventional PMI ends (0 if no PMI)" }, "conventionalRequiresPmi": { "type": "boolean" }, "fhaMipMonthsModeled": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "fhaUfmipFinancedIntoLoan": { "type": "boolean" } }, "required": [ "programALabel", "programBLabel", "baseLoanAmount", "downPaymentPercent", "expectedOwnershipYears", "expectedOwnershipMonths", "sharedHousing", "programA", "programB", "programAHousing", "programBHousing", "monthlyHousingDifference", "lifetimeLoanCostDifference", "upfrontDifference", "monthlyLoanPaymentDifference", "lowerMonthlyLoanPayment", "lowerLoanCostOverOwnershipPeriod", "breakEvenOwnershipYears", "conventionalPmiEndsAfterYears", "conventionalRequiresPmi", "fhaMipMonthsModeled", "fhaUfmipFinancedIntoLoan" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/buy-vs-rent": { "post": { "operationId": "compare_buy_vs_rent", "summary": "Compare buying vs renting", "description": "Compares buying (program A) vs renting (program B) over expected stay years. Returns ownership cash flow, home equity, renter investment portfolio (opportunity cost when buy costs more), net worth at horizon assuming home sale, break-even year, month-1 and average monthly cost differences, and yearly snapshots.", "tags": [ "comparison" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "propertyTaxRate": { "default": 1.2, "type": "number", "minimum": 0 }, "annualHomeInsurance": { "default": 1200, "type": "number", "minimum": 0 }, "monthlyHOA": { "default": 0, "type": "number", "minimum": 0 }, "pmiRatePercent": { "default": 0.5, "type": "number", "minimum": 0 }, "closingCostsPercent": { "default": 3, "type": "number", "minimum": 0 }, "closingCosts": { "type": "number", "minimum": 0 }, "annualHomeAppreciationPercent": { "default": 3, "type": "number", "minimum": 0 }, "annualMaintenancePercent": { "default": 1, "type": "number", "minimum": 0 }, "sellingCostPercent": { "default": 6, "type": "number", "minimum": 0 }, "monthlyRent": { "type": "number", "minimum": 0 }, "annualRentGrowthPercent": { "default": 3, "type": "number", "minimum": 0 }, "rentersInsuranceAnnual": { "default": 240, "type": "number", "minimum": 0 }, "annualInvestmentReturnPercent": { "default": 5, "type": "number", "minimum": 0 }, "expectedStayYears": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "monthlyGrossIncome": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "homePrice", "downPayment", "interestRate", "monthlyRent" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "interestRate": 6.74, "loanTermYears": 30, "propertyTaxRate": 1.07, "annualHomeInsurance": 1689, "monthlyRent": 2400, "expectedStayYears": 10, "annualInvestmentReturnPercent": 5 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "programALabel": { "type": "string", "const": "Buy" }, "programBLabel": { "type": "string", "const": "Rent" }, "loanAmount": { "type": "number" }, "downPaymentPercent": { "type": "number" }, "expectedStayYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "expectedStayMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "programA": { "type": "object", "properties": { "initialCashToClose": { "type": "number" }, "closingCosts": { "type": "number" }, "monthlyOwnershipCostMonth1": { "type": "number" }, "totalOwnershipCashOutThroughHorizon": { "type": "number" }, "totalInterestPaidThroughHorizon": { "type": "number" }, "totalPrincipalPaidThroughHorizon": { "type": "number" }, "homeValueAtHorizon": { "type": "number" }, "loanBalanceAtHorizon": { "type": "number" }, "equityAtHorizon": { "type": "number" }, "homeEquityPercentageAtHorizon": { "type": "number", "description": "equity / homeValue at horizon (%)" }, "sellingCostsAtHorizon": { "type": "number" }, "netHomeEquityAfterSellingCosts": { "type": "number" }, "netWorthAtHorizon": { "type": "number" } }, "required": [ "initialCashToClose", "closingCosts", "monthlyOwnershipCostMonth1", "totalOwnershipCashOutThroughHorizon", "totalInterestPaidThroughHorizon", "totalPrincipalPaidThroughHorizon", "homeValueAtHorizon", "loanBalanceAtHorizon", "equityAtHorizon", "homeEquityPercentageAtHorizon", "sellingCostsAtHorizon", "netHomeEquityAfterSellingCosts", "netWorthAtHorizon" ], "additionalProperties": false }, "programB": { "type": "object", "properties": { "monthlyRentMonth1": { "type": "number" }, "totalRentPaidThroughHorizon": { "type": "number" }, "totalRentersInsuranceThroughHorizon": { "type": "number" }, "initialInvestedCapital": { "type": "number" }, "totalMonthlySurplusInvested": { "type": "number" }, "totalContributions": { "type": "number" }, "investmentGainsThroughHorizon": { "type": "number" }, "investmentPortfolioAtHorizon": { "type": "number" }, "netWorthAtHorizon": { "type": "number" } }, "required": [ "monthlyRentMonth1", "totalRentPaidThroughHorizon", "totalRentersInsuranceThroughHorizon", "initialInvestedCapital", "totalMonthlySurplusInvested", "totalContributions", "investmentGainsThroughHorizon", "investmentPortfolioAtHorizon", "netWorthAtHorizon" ], "additionalProperties": false }, "monthlyCostDifference": { "type": "number", "description": "Buy minus rent, month 1 only" }, "averageMonthlyCostDifferenceThroughHorizon": { "type": "number" }, "cumulativeCashOutDifference": { "type": "number" }, "netWorthDifference": { "type": "number" }, "higherNetWorthAtHorizon": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "lowerCumulativeCashOut": { "type": "string", "enum": [ "programA", "programB", "equal" ] }, "breakEvenYears": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "breakEvenMonths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "horizonSnapshots": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "buyNetWorth": { "type": "number" }, "rentNetWorth": { "type": "number" }, "buyCumulativeCashOut": { "type": "number" }, "rentCumulativeCashOut": { "type": "number" }, "homeValue": { "type": "number" }, "equity": { "type": "number" }, "loanBalance": { "type": "number" } }, "required": [ "year", "buyNetWorth", "rentNetWorth", "buyCumulativeCashOut", "rentCumulativeCashOut", "homeValue", "equity", "loanBalance" ], "additionalProperties": false } }, "monthlyOwnershipCostAsPercentOfIncome": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthlyRentAsPercentOfIncome": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "exceeds28PercentGuidelineBuy": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "exceeds28PercentGuidelineRent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "programALabel", "programBLabel", "loanAmount", "downPaymentPercent", "expectedStayYears", "expectedStayMonths", "programA", "programB", "monthlyCostDifference", "averageMonthlyCostDifferenceThroughHorizon", "cumulativeCashOutDifference", "netWorthDifference", "higherNetWorthAtHorizon", "lowerCumulativeCashOut", "breakEvenYears", "breakEvenMonths", "horizonSnapshots", "monthlyOwnershipCostAsPercentOfIncome", "monthlyRentAsPercentOfIncome", "exceeds28PercentGuidelineBuy", "exceeds28PercentGuidelineRent" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/closing-costs": { "post": { "operationId": "estimate_closing_costs", "summary": "Estimate closing costs and cash to close", "description": "Estimates potential buyer closing costs and cash to close from itemized loan, title/settlement, prepaid, escrow, and credit lines. Returns category subtotals, net closing costs, cash to close, prepaid interest per day, and estimated recurring monthly escrow.", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "transactionType": { "default": "purchase", "description": "Affects down payment in cash-to-close", "type": "string", "enum": [ "purchase", "refinance" ] }, "noteRate": { "default": 0, "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "pointsPercent": { "default": 0, "type": "number", "minimum": 0 }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string", "enum": [ "loan", "titleSettlement", "prepaid", "escrow", "credit" ] }, "label": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "includedInCashToClose": { "type": "boolean" } }, "required": [ "id", "category", "label", "amount" ], "additionalProperties": false } }, "annualPropertyTax": { "type": "number", "minimum": 0 }, "annualHomeInsurance": { "type": "number", "minimum": 0 }, "sellerCredit": { "type": "number", "minimum": 0 }, "lenderCredit": { "type": "number", "minimum": 0 }, "editableDefaultTemplateVersion": { "type": "string" } }, "required": [ "homePrice", "downPayment", "lineItems" ], "additionalProperties": false }, "example": { "homePrice": 400000, "downPayment": 80000, "noteRate": 6.74, "transactionType": "purchase", "lineItems": [ { "id": "origination_fee", "category": "loan", "label": "Origination fee", "amount": 2500 }, { "id": "title", "category": "titleSettlement", "label": "Title & settlement", "amount": 3000 }, { "id": "prepaid_interest", "category": "prepaid", "label": "Prepaid interest", "amount": 850 }, { "id": "escrow_tax", "category": "escrow", "label": "Tax escrow", "amount": 1200 } ], "annualPropertyTax": 4800, "annualHomeInsurance": 1200 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "homePrice": { "type": "number" }, "downPayment": { "type": "number" }, "loanAmount": { "type": "number" }, "transactionType": { "type": "string", "enum": [ "purchase", "refinance" ] }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string", "enum": [ "loan", "titleSettlement", "prepaid", "escrow", "credit" ] }, "label": { "type": "string" }, "amount": { "type": "number", "minimum": 0 }, "includedInCashToClose": { "type": "boolean" } }, "required": [ "id", "category", "label", "amount" ], "additionalProperties": false } }, "subtotalLoanCosts": { "type": "number" }, "subtotalTitleAndSettlement": { "type": "number" }, "subtotalPrepaids": { "type": "number" }, "subtotalEscrowReserves": { "type": "number" }, "subtotalCredits": { "type": "number" }, "totalClosingCostsBeforeCredits": { "type": "number" }, "netClosingCosts": { "type": "number" }, "downPaymentAmount": { "type": "number" }, "cashToClose": { "type": "number" }, "closingCostsAsPercentOfHomePrice": { "type": "number" }, "cashToCloseAsPercentOfHomePrice": { "type": "number" }, "estimatedRecurringMonthlyEscrow": { "type": "number" }, "estimatedPrepaidInterestPerDay": { "type": "number" }, "editableDefaultTemplateVersion": { "type": "string" } }, "required": [ "homePrice", "downPayment", "loanAmount", "transactionType", "lineItems", "subtotalLoanCosts", "subtotalTitleAndSettlement", "subtotalPrepaids", "subtotalEscrowReserves", "subtotalCredits", "totalClosingCostsBeforeCredits", "netClosingCosts", "downPaymentAmount", "cashToClose", "closingCostsAsPercentOfHomePrice", "cashToCloseAsPercentOfHomePrice", "estimatedRecurringMonthlyEscrow", "estimatedPrepaidInterestPerDay" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/amortization": { "post": { "operationId": "generate_amortization_schedule", "summary": "Generate amortization schedule summary", "description": "Generates educational fixed-rate amortization: monthly P&I, total interest, payoff date, annual summaries with cumulative principal/interest, and first-five-year milestones. Set includeSchedule true for full month-by-month rows.", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "loanAmount": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "includeSchedule": { "default": false, "type": "boolean" } }, "required": [ "loanAmount", "interestRate", "loanTermYears" ], "additionalProperties": false }, "example": { "loanAmount": 280000, "interestRate": 6.74, "loanTermYears": 30, "includeSchedule": false } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "interestRate": { "type": "number" }, "loanTermYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "monthlyPI": { "type": "number" }, "numberOfPayments": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "totalInterest": { "type": "number" }, "totalPrincipal": { "type": "number" }, "totalOfPayments": { "type": "number" }, "payoffDate": { "type": "string" }, "annualSummaries": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "monthsInYear": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalPayment": { "type": "number" }, "totalPrincipal": { "type": "number" }, "totalInterest": { "type": "number" }, "endingBalance": { "type": "number" }, "cumulativePrincipalPaid": { "type": "number" }, "cumulativeInterestPaid": { "type": "number" } }, "required": [ "year", "monthsInYear", "totalPayment", "totalPrincipal", "totalInterest", "endingBalance", "cumulativePrincipalPaid", "cumulativeInterestPaid" ], "additionalProperties": false } }, "principalPaidFirst5Years": { "type": "number" }, "interestPaidFirst5Years": { "type": "number" }, "remainingBalanceAfter5Years": { "type": "number" }, "interestShareFirst5Years": { "type": "number" }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } } }, "required": [ "loanAmount", "interestRate", "loanTermYears", "monthlyPI", "numberOfPayments", "totalInterest", "totalPrincipal", "totalOfPayments", "payoffDate", "annualSummaries", "principalPaidFirst5Years", "interestPaidFirst5Years", "remainingBalanceAfter5Years", "interestShareFirst5Years" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/prepayment": { "post": { "operationId": "calculate_prepayment_penalty", "summary": "Estimate prepayment penalty and cash required", "description": "Estimates potential prepayment penalty from user-entered balance, prepayment amount, and penalty terms. Returns remaining balance, prepayment, penalty, estimated cash required to prepay, balance source, assumptions used, and optional user-driven comparisons (comparisonMode defaults to none).", "tags": [ "tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "remainingBalance": { "type": "number", "minimum": 0 }, "originalLoanAmount": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "paymentsMadeMonths": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "format": "int32" }, "prepaymentScenario": { "default": "full_payoff", "type": "string", "enum": [ "full_payoff", "partial_prepayment", "refinance_payoff" ] }, "prepaymentAmount": { "type": "number", "minimum": 0 }, "penaltyType": { "type": "string", "enum": [ "none", "percent_of_prepayment", "percent_of_remaining_balance", "months_of_interest", "flat_fee" ] }, "penaltyPercent": { "default": 0, "type": "number", "minimum": 0 }, "penaltyMonthsOfInterest": { "default": 0, "type": "number", "minimum": 0 }, "flatPenaltyAmount": { "default": 0, "type": "number", "minimum": 0 }, "comparisonMode": { "default": "none", "type": "string", "enum": [ "none", "extra_payment", "refinance" ] }, "estimatedInterestSaved": { "type": "number", "minimum": 0 }, "refinanceMonthlySavings": { "type": "number" }, "refinanceClosingCosts": { "type": "number", "minimum": 0 }, "comparisonHorizonMonths": { "default": 60, "type": "integer", "minimum": 1, "maximum": 360, "format": "int32" } }, "required": [ "interestRate", "penaltyType" ], "additionalProperties": false }, "example": { "remainingBalance": 280000, "interestRate": 6.74, "prepaymentScenario": "partial_prepayment", "prepaymentAmount": 20000, "penaltyType": "percent_of_prepayment", "penaltyPercent": 2, "comparisonMode": "none" } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "remainingBalance": { "type": "number" }, "prepaymentAmount": { "type": "number" }, "penaltyAmount": { "type": "number" }, "estimatedCashRequiredToPrepay": { "type": "number" }, "penaltyType": { "type": "string", "enum": [ "none", "percent_of_prepayment", "percent_of_remaining_balance", "months_of_interest", "flat_fee" ] }, "prepaymentScenario": { "type": "string", "enum": [ "full_payoff", "partial_prepayment", "refinance_payoff" ] }, "penaltyCalculationDescription": { "type": "string" }, "monthlyInterestAtBalance": { "type": "number" }, "penaltyAsPercentOfPrepayment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "penaltyAsPercentOfBalance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "balanceSource": { "type": "string", "enum": [ "user_entered", "estimated_from_amortization" ] }, "remainingTermMonthsEstimate": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "penaltyTriggerDisclosure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assumptionsUsed": { "type": "array", "items": { "type": "string" } }, "comparisonMode": { "type": "string", "enum": [ "none", "extra_payment", "refinance" ] }, "netVsExtraPayment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "modeledExtraPaymentFavorable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "netVsRefinanceAtHorizon": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "modeledRefinanceFavorableAtHorizon": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "remainingBalance", "prepaymentAmount", "penaltyAmount", "estimatedCashRequiredToPrepay", "penaltyType", "prepaymentScenario", "penaltyCalculationDescription", "monthlyInterestAtBalance", "penaltyAsPercentOfPrepayment", "penaltyAsPercentOfBalance", "balanceSource", "remainingTermMonthsEstimate", "penaltyTriggerDisclosure", "assumptionsUsed", "comparisonMode", "netVsExtraPayment", "modeledExtraPaymentFavorable", "netVsRefinanceAtHorizon", "modeledRefinanceFavorableAtHorizon" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/cash-flow": { "post": { "operationId": "analyze_cash_flow", "summary": "Model rental property cash flow", "description": "Educational rental property cash flow analysis from user-entered rent, vacancy, operating expenses, and financing. Returns modeled NOI, debt service (P&I), monthly and annual cash flow, cash-on-cash return, DSCR, expense ratio, and break-even occupancy. Not live market data, tax advice, or investment advice.", "tags": [ "investment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchasePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "interestRatePercent": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "loanAmount": { "type": "number", "minimum": 0 }, "grossMonthlyRent": { "type": "number", "minimum": 0 }, "vacancyRatePercent": { "default": 5, "type": "number", "minimum": 0, "maximum": 100 }, "otherMonthlyIncome": { "default": 0, "type": "number", "minimum": 0 }, "operatingExpensesFixedMonthly": { "default": { "propertyTaxMonthly": 0, "insuranceMonthly": 0, "hoaMonthly": 0, "utilitiesMonthly": 0, "otherFixedMonthly": 0 }, "type": "object", "properties": { "propertyTaxMonthly": { "default": 0, "type": "number", "minimum": 0 }, "insuranceMonthly": { "default": 0, "type": "number", "minimum": 0 }, "hoaMonthly": { "default": 0, "type": "number", "minimum": 0 }, "utilitiesMonthly": { "default": 0, "type": "number", "minimum": 0 }, "otherFixedMonthly": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "propertyTaxMonthly", "insuranceMonthly", "hoaMonthly", "utilitiesMonthly", "otherFixedMonthly" ], "additionalProperties": false }, "operatingExpensesPercentBased": { "default": { "propertyManagementPercent": 0 }, "type": "object", "properties": { "propertyManagementPercent": { "default": 0, "type": "number", "minimum": 0 }, "maintenancePercentOfRent": { "type": "number", "minimum": 0 }, "capexReservePercent": { "type": "number", "minimum": 0 } }, "required": [ "propertyManagementPercent" ], "additionalProperties": false }, "maintenanceFixedMonthly": { "type": "number", "minimum": 0 }, "analysisHorizonYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "annualRentGrowthPercent": { "type": "number", "minimum": 0 }, "annualExpenseGrowthPercent": { "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "type": "number", "minimum": 0 } }, "required": [ "purchasePrice", "downPayment", "interestRatePercent", "grossMonthlyRent" ], "additionalProperties": false }, "example": { "purchasePrice": 300000, "downPayment": 60000, "closingCosts": 9000, "interestRatePercent": 7, "loanTermYears": 30, "grossMonthlyRent": 2500, "vacancyRatePercent": 5, "otherMonthlyIncome": 0, "operatingExpensesFixedMonthly": { "propertyTaxMonthly": 300, "insuranceMonthly": 150, "hoaMonthly": 0, "utilitiesMonthly": 100, "otherFixedMonthly": 50 }, "operatingExpensesPercentBased": { "propertyManagementPercent": 8, "maintenancePercentOfRent": 5 } } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "propertyPerformance": { "type": "object", "properties": { "grossScheduledRentAnnual": { "type": "number" }, "vacancyLossAnnual": { "type": "number" }, "effectiveGrossIncomeAnnual": { "type": "number" }, "effectiveGrossIncomeMonthly": { "type": "number" }, "operatingExpensesFixedAnnual": { "type": "number" }, "operatingExpensesPercentBasedAnnual": { "type": "number" }, "totalOperatingExpensesAnnual": { "type": "number" }, "totalOperatingExpensesMonthly": { "type": "number" }, "noiAnnual": { "type": "number" }, "noiMonthly": { "type": "number" }, "capRatePercent": { "type": "number" }, "expenseRatioPercent": { "type": "number" }, "debtYieldPercent": { "type": "number" }, "breakEvenOccupancyRatePercent": { "type": "number" }, "grossRentMultiplier": { "type": "number" } }, "required": [ "grossScheduledRentAnnual", "vacancyLossAnnual", "effectiveGrossIncomeAnnual", "effectiveGrossIncomeMonthly", "operatingExpensesFixedAnnual", "operatingExpensesPercentBasedAnnual", "totalOperatingExpensesAnnual", "totalOperatingExpensesMonthly", "noiAnnual", "noiMonthly", "capRatePercent", "expenseRatioPercent", "debtYieldPercent", "breakEvenOccupancyRatePercent", "grossRentMultiplier" ], "additionalProperties": false }, "financing": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "monthlyPI": { "type": "number" }, "annualDebtService": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "totalCashInvested": { "type": "number" } }, "required": [ "loanAmount", "monthlyPI", "annualDebtService", "debtServiceBasis", "totalCashInvested" ], "additionalProperties": false }, "cashFlow": { "type": "object", "properties": { "monthlyCashFlow": { "type": "number" }, "annualCashFlow": { "type": "number" }, "cashOnCashReturnPercent": { "type": "number" } }, "required": [ "monthlyCashFlow", "annualCashFlow", "cashOnCashReturnPercent" ], "additionalProperties": false }, "dscr": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "annualProjectionRows": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "grossRent": { "type": "number" }, "vacancyLoss": { "type": "number" }, "effectiveGrossIncome": { "type": "number" }, "operatingExpenses": { "type": "number" }, "noi": { "type": "number" }, "debtService": { "type": "number" }, "cashFlow": { "type": "number" }, "loanBalance": { "type": "number" }, "propertyValue": { "type": "number" }, "equity": { "type": "number" } }, "required": [ "year", "grossRent", "vacancyLoss", "effectiveGrossIncome", "operatingExpenses", "noi", "debtService", "cashFlow" ], "additionalProperties": false } } }, "required": [ "propertyPerformance", "financing", "cashFlow", "dscr", "debtServiceBasis", "annualProjectionRows" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/cap-rate": { "post": { "operationId": "calculate_cap_rate", "summary": "Model rental property cap rate", "description": "Educational cap rate from user-entered rent, vacancy, operating expenses, and property value. Cap rate = annual NOI ÷ property value (before debt). Returns property performance, modeled cap rate, expense ratio, and optional financing/cash flow context. Not live market cap rates, tax advice, or investment advice.", "tags": [ "investment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchasePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "interestRatePercent": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "loanAmount": { "type": "number", "minimum": 0 }, "grossMonthlyRent": { "type": "number", "minimum": 0 }, "vacancyRatePercent": { "default": 5, "type": "number", "minimum": 0, "maximum": 100 }, "otherMonthlyIncome": { "default": 0, "type": "number", "minimum": 0 }, "operatingExpensesFixedMonthly": { "default": { "propertyTaxMonthly": 0, "insuranceMonthly": 0, "hoaMonthly": 0, "utilitiesMonthly": 0, "otherFixedMonthly": 0 }, "type": "object", "properties": { "propertyTaxMonthly": { "default": 0, "type": "number", "minimum": 0 }, "insuranceMonthly": { "default": 0, "type": "number", "minimum": 0 }, "hoaMonthly": { "default": 0, "type": "number", "minimum": 0 }, "utilitiesMonthly": { "default": 0, "type": "number", "minimum": 0 }, "otherFixedMonthly": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "propertyTaxMonthly", "insuranceMonthly", "hoaMonthly", "utilitiesMonthly", "otherFixedMonthly" ], "additionalProperties": false }, "operatingExpensesPercentBased": { "default": { "propertyManagementPercent": 0 }, "type": "object", "properties": { "propertyManagementPercent": { "default": 0, "type": "number", "minimum": 0 }, "maintenancePercentOfRent": { "type": "number", "minimum": 0 }, "capexReservePercent": { "type": "number", "minimum": 0 } }, "required": [ "propertyManagementPercent" ], "additionalProperties": false }, "maintenanceFixedMonthly": { "type": "number", "minimum": 0 }, "analysisHorizonYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "annualRentGrowthPercent": { "type": "number", "minimum": 0 }, "annualExpenseGrowthPercent": { "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "type": "number", "minimum": 0 } }, "required": [ "purchasePrice", "downPayment", "interestRatePercent", "grossMonthlyRent" ], "additionalProperties": false }, "example": { "purchasePrice": 300000, "downPayment": 60000, "closingCosts": 9000, "interestRatePercent": 7, "loanTermYears": 30, "grossMonthlyRent": 2500, "vacancyRatePercent": 5, "otherMonthlyIncome": 0, "operatingExpensesFixedMonthly": { "propertyTaxMonthly": 300, "insuranceMonthly": 150, "hoaMonthly": 0, "utilitiesMonthly": 100, "otherFixedMonthly": 50 }, "operatingExpensesPercentBased": { "propertyManagementPercent": 8, "maintenancePercentOfRent": 5 } } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "propertyPerformance": { "type": "object", "properties": { "grossScheduledRentAnnual": { "type": "number" }, "vacancyLossAnnual": { "type": "number" }, "effectiveGrossIncomeAnnual": { "type": "number" }, "effectiveGrossIncomeMonthly": { "type": "number" }, "operatingExpensesFixedAnnual": { "type": "number" }, "operatingExpensesPercentBasedAnnual": { "type": "number" }, "totalOperatingExpensesAnnual": { "type": "number" }, "totalOperatingExpensesMonthly": { "type": "number" }, "noiAnnual": { "type": "number" }, "noiMonthly": { "type": "number" }, "capRatePercent": { "type": "number" }, "expenseRatioPercent": { "type": "number" }, "debtYieldPercent": { "type": "number" }, "breakEvenOccupancyRatePercent": { "type": "number" }, "grossRentMultiplier": { "type": "number" } }, "required": [ "grossScheduledRentAnnual", "vacancyLossAnnual", "effectiveGrossIncomeAnnual", "effectiveGrossIncomeMonthly", "operatingExpensesFixedAnnual", "operatingExpensesPercentBasedAnnual", "totalOperatingExpensesAnnual", "totalOperatingExpensesMonthly", "noiAnnual", "noiMonthly", "capRatePercent", "expenseRatioPercent", "debtYieldPercent", "breakEvenOccupancyRatePercent", "grossRentMultiplier" ], "additionalProperties": false }, "propertyValue": { "type": "number" }, "capRatePercent": { "type": "number" }, "financing": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "monthlyPI": { "type": "number" }, "annualDebtService": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "totalCashInvested": { "type": "number" } }, "required": [ "loanAmount", "monthlyPI", "annualDebtService", "debtServiceBasis", "totalCashInvested" ], "additionalProperties": false }, "cashFlow": { "type": "object", "properties": { "monthlyCashFlow": { "type": "number" }, "annualCashFlow": { "type": "number" }, "cashOnCashReturnPercent": { "type": "number" } }, "required": [ "monthlyCashFlow", "annualCashFlow", "cashOnCashReturnPercent" ], "additionalProperties": false }, "dscr": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" } }, "required": [ "propertyPerformance", "propertyValue", "capRatePercent", "financing", "cashFlow", "dscr", "debtServiceBasis" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/dscr": { "post": { "operationId": "calculate_dscr", "summary": "Model rental property DSCR", "description": "Educational debt service coverage ratio from user-entered rent, vacancy, operating expenses, and financing. Modeled DSCR = annual NOI ÷ annual P&I debt service (debtServiceBasis: pi). Returns NOI, debt service, debt yield, cap rate context, and break-even occupancy. Not loan approval, lender underwriting, or investment advice.", "tags": [ "investment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchasePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "interestRatePercent": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "loanAmount": { "type": "number", "minimum": 0 }, "grossMonthlyRent": { "type": "number", "minimum": 0 }, "vacancyRatePercent": { "default": 5, "type": "number", "minimum": 0, "maximum": 100 }, "otherMonthlyIncome": { "default": 0, "type": "number", "minimum": 0 }, "operatingExpensesFixedMonthly": { "default": { "propertyTaxMonthly": 0, "insuranceMonthly": 0, "hoaMonthly": 0, "utilitiesMonthly": 0, "otherFixedMonthly": 0 }, "type": "object", "properties": { "propertyTaxMonthly": { "default": 0, "type": "number", "minimum": 0 }, "insuranceMonthly": { "default": 0, "type": "number", "minimum": 0 }, "hoaMonthly": { "default": 0, "type": "number", "minimum": 0 }, "utilitiesMonthly": { "default": 0, "type": "number", "minimum": 0 }, "otherFixedMonthly": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "propertyTaxMonthly", "insuranceMonthly", "hoaMonthly", "utilitiesMonthly", "otherFixedMonthly" ], "additionalProperties": false }, "operatingExpensesPercentBased": { "default": { "propertyManagementPercent": 0 }, "type": "object", "properties": { "propertyManagementPercent": { "default": 0, "type": "number", "minimum": 0 }, "maintenancePercentOfRent": { "type": "number", "minimum": 0 }, "capexReservePercent": { "type": "number", "minimum": 0 } }, "required": [ "propertyManagementPercent" ], "additionalProperties": false }, "maintenanceFixedMonthly": { "type": "number", "minimum": 0 }, "analysisHorizonYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "annualRentGrowthPercent": { "type": "number", "minimum": 0 }, "annualExpenseGrowthPercent": { "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "type": "number", "minimum": 0 } }, "required": [ "purchasePrice", "downPayment", "interestRatePercent", "grossMonthlyRent" ], "additionalProperties": false }, "example": { "purchasePrice": 300000, "downPayment": 60000, "closingCosts": 9000, "interestRatePercent": 7, "loanTermYears": 30, "grossMonthlyRent": 2500, "vacancyRatePercent": 5, "otherMonthlyIncome": 0, "operatingExpensesFixedMonthly": { "propertyTaxMonthly": 300, "insuranceMonthly": 150, "hoaMonthly": 0, "utilitiesMonthly": 100, "otherFixedMonthly": 50 }, "operatingExpensesPercentBased": { "propertyManagementPercent": 8, "maintenancePercentOfRent": 5 } } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "dscr": { "type": "number" }, "noiAnnual": { "type": "number" }, "annualDebtService": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "monthlyPI": { "type": "number" }, "loanAmount": { "type": "number" }, "propertyPerformance": { "type": "object", "properties": { "grossScheduledRentAnnual": { "type": "number" }, "vacancyLossAnnual": { "type": "number" }, "effectiveGrossIncomeAnnual": { "type": "number" }, "effectiveGrossIncomeMonthly": { "type": "number" }, "operatingExpensesFixedAnnual": { "type": "number" }, "operatingExpensesPercentBasedAnnual": { "type": "number" }, "totalOperatingExpensesAnnual": { "type": "number" }, "totalOperatingExpensesMonthly": { "type": "number" }, "noiAnnual": { "type": "number" }, "noiMonthly": { "type": "number" }, "capRatePercent": { "type": "number" }, "expenseRatioPercent": { "type": "number" }, "debtYieldPercent": { "type": "number" }, "breakEvenOccupancyRatePercent": { "type": "number" }, "grossRentMultiplier": { "type": "number" } }, "required": [ "grossScheduledRentAnnual", "vacancyLossAnnual", "effectiveGrossIncomeAnnual", "effectiveGrossIncomeMonthly", "operatingExpensesFixedAnnual", "operatingExpensesPercentBasedAnnual", "totalOperatingExpensesAnnual", "totalOperatingExpensesMonthly", "noiAnnual", "noiMonthly", "capRatePercent", "expenseRatioPercent", "debtYieldPercent", "breakEvenOccupancyRatePercent", "grossRentMultiplier" ], "additionalProperties": false }, "financing": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "monthlyPI": { "type": "number" }, "annualDebtService": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "totalCashInvested": { "type": "number" } }, "required": [ "loanAmount", "monthlyPI", "annualDebtService", "debtServiceBasis", "totalCashInvested" ], "additionalProperties": false }, "cashFlow": { "type": "object", "properties": { "monthlyCashFlow": { "type": "number" }, "annualCashFlow": { "type": "number" }, "cashOnCashReturnPercent": { "type": "number" } }, "required": [ "monthlyCashFlow", "annualCashFlow", "cashOnCashReturnPercent" ], "additionalProperties": false } }, "required": [ "dscr", "noiAnnual", "annualDebtService", "debtServiceBasis", "monthlyPI", "loanAmount", "propertyPerformance", "financing", "cashFlow" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/roi": { "post": { "operationId": "analyze_roi", "summary": "Model rental property total return", "description": "Educational modeled total return over a user-chosen horizon. Combines cumulative modeled cash flow and projected equity at sale from appreciation assumptions. Returns modeled total return % and $, cash-on-cash (year one), annual projection rows. Not IRR/XIRR, not tax-adjusted, not investment advice.", "tags": [ "investment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "purchasePrice": { "type": "number", "minimum": 0 }, "downPayment": { "type": "number", "minimum": 0 }, "closingCosts": { "default": 0, "type": "number", "minimum": 0 }, "interestRatePercent": { "type": "number", "minimum": 0 }, "loanTermYears": { "default": 30, "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "loanAmount": { "type": "number", "minimum": 0 }, "grossMonthlyRent": { "type": "number", "minimum": 0 }, "vacancyRatePercent": { "default": 5, "type": "number", "minimum": 0, "maximum": 100 }, "otherMonthlyIncome": { "default": 0, "type": "number", "minimum": 0 }, "operatingExpensesFixedMonthly": { "default": { "propertyTaxMonthly": 0, "insuranceMonthly": 0, "hoaMonthly": 0, "utilitiesMonthly": 0, "otherFixedMonthly": 0 }, "type": "object", "properties": { "propertyTaxMonthly": { "default": 0, "type": "number", "minimum": 0 }, "insuranceMonthly": { "default": 0, "type": "number", "minimum": 0 }, "hoaMonthly": { "default": 0, "type": "number", "minimum": 0 }, "utilitiesMonthly": { "default": 0, "type": "number", "minimum": 0 }, "otherFixedMonthly": { "default": 0, "type": "number", "minimum": 0 } }, "required": [ "propertyTaxMonthly", "insuranceMonthly", "hoaMonthly", "utilitiesMonthly", "otherFixedMonthly" ], "additionalProperties": false }, "operatingExpensesPercentBased": { "default": { "propertyManagementPercent": 0 }, "type": "object", "properties": { "propertyManagementPercent": { "default": 0, "type": "number", "minimum": 0 }, "maintenancePercentOfRent": { "type": "number", "minimum": 0 }, "capexReservePercent": { "type": "number", "minimum": 0 } }, "required": [ "propertyManagementPercent" ], "additionalProperties": false }, "maintenanceFixedMonthly": { "type": "number", "minimum": 0 }, "analysisHorizonYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "annualRentGrowthPercent": { "type": "number", "minimum": 0 }, "annualExpenseGrowthPercent": { "type": "number", "minimum": 0 }, "annualAppreciationPercent": { "type": "number", "minimum": 0 } }, "required": [ "purchasePrice", "downPayment", "interestRatePercent", "grossMonthlyRent" ], "additionalProperties": false }, "example": { "purchasePrice": 300000, "downPayment": 60000, "closingCosts": 9000, "interestRatePercent": 7, "loanTermYears": 30, "grossMonthlyRent": 2500, "vacancyRatePercent": 5, "otherMonthlyIncome": 0, "operatingExpensesFixedMonthly": { "propertyTaxMonthly": 300, "insuranceMonthly": 150, "hoaMonthly": 0, "utilitiesMonthly": 100, "otherFixedMonthly": 50 }, "operatingExpensesPercentBased": { "propertyManagementPercent": 8, "maintenancePercentOfRent": 5 }, "analysisHorizonYears": 5, "annualRentGrowthPercent": 2, "annualExpenseGrowthPercent": 2, "annualAppreciationPercent": 3 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "horizon": { "type": "object", "properties": { "analysisHorizonYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "modeledTotalReturnPercent": { "type": "number" }, "equityAtHorizon": { "type": "number" }, "saleProceedsEducational": { "type": "number" }, "cumulativeCashFlowThroughHorizon": { "type": "number" } }, "required": [ "analysisHorizonYears", "modeledTotalReturnPercent", "equityAtHorizon", "saleProceedsEducational", "cumulativeCashFlowThroughHorizon" ], "additionalProperties": false }, "cashFlow": { "type": "object", "properties": { "monthlyCashFlow": { "type": "number" }, "annualCashFlow": { "type": "number" }, "cashOnCashReturnPercent": { "type": "number" } }, "required": [ "monthlyCashFlow", "annualCashFlow", "cashOnCashReturnPercent" ], "additionalProperties": false }, "financing": { "type": "object", "properties": { "loanAmount": { "type": "number" }, "monthlyPI": { "type": "number" }, "annualDebtService": { "type": "number" }, "debtServiceBasis": { "type": "string", "const": "pi" }, "totalCashInvested": { "type": "number" } }, "required": [ "loanAmount", "monthlyPI", "annualDebtService", "debtServiceBasis", "totalCashInvested" ], "additionalProperties": false }, "annualProjectionRows": { "type": "array", "items": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "grossRent": { "type": "number" }, "vacancyLoss": { "type": "number" }, "effectiveGrossIncome": { "type": "number" }, "operatingExpenses": { "type": "number" }, "noi": { "type": "number" }, "debtService": { "type": "number" }, "cashFlow": { "type": "number" }, "loanBalance": { "type": "number" }, "propertyValue": { "type": "number" }, "equity": { "type": "number" } }, "required": [ "year", "grossRent", "vacancyLoss", "effectiveGrossIncome", "operatingExpenses", "noi", "debtService", "cashFlow" ], "additionalProperties": false } }, "modeledTotalReturnDollars": { "type": "number" }, "projectedPropertyValueAtHorizon": { "type": "number" }, "assumptions": { "type": "object", "properties": { "analysisHorizonYears": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "annualRentGrowthPercent": { "type": "number" }, "annualExpenseGrowthPercent": { "type": "number" }, "annualAppreciationPercent": { "type": "number" } }, "required": [ "analysisHorizonYears", "annualRentGrowthPercent", "annualExpenseGrowthPercent", "annualAppreciationPercent" ], "additionalProperties": false } }, "required": [ "horizon", "cashFlow", "financing", "annualProjectionRows", "modeledTotalReturnDollars", "projectedPropertyValueAtHorizon", "assumptions" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/api/calculators/extra-payment": { "post": { "operationId": "analyze_extra_payments", "summary": "Analyse extra mortgage payments", "description": "Analyses how monthly and one-time extra principal payments affect a fixed-rate mortgage. Returns interest saved, months and years saved, illustrative payoff dates, effective interest reduction, and optional amortization schedules when includeSchedule is true.", "tags": [ "mortgage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "loanAmount": { "type": "number", "minimum": 0 }, "interestRate": { "type": "number", "minimum": 0 }, "loanTermYears": { "type": "integer", "minimum": 1, "maximum": 50, "format": "int32" }, "monthlyExtraPayment": { "default": 0, "type": "number", "minimum": 0 }, "oneTimeExtraPayment": { "default": 0, "type": "number", "minimum": 0 }, "oneTimePaymentMonth": { "default": 12, "type": "integer", "minimum": 1, "maximum": 9007199254740991, "format": "int32" }, "includeSchedule": { "default": false, "type": "boolean" } }, "required": [ "loanAmount", "interestRate", "loanTermYears" ], "additionalProperties": false }, "example": { "loanAmount": 280000, "interestRate": 6.74, "loanTermYears": 30, "monthlyExtraPayment": 200, "oneTimeExtraPayment": 5000, "oneTimePaymentMonth": 12 } } } }, "responses": { "200": { "description": "Successful calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "calculatorId": { "type": "string", "maxLength": 50 }, "data": { "type": "object", "properties": { "monthlyPI": { "type": "number" }, "baselinePayoffMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "acceleratedPayoffMonths": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "monthsSaved": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "format": "int32" }, "yearsSaved": { "type": "number" }, "baselineTotalInterest": { "type": "number" }, "acceleratedTotalInterest": { "type": "number" }, "interestSaved": { "type": "number" }, "totalExtraPaid": { "type": "number" }, "baselinePayoffDate": { "type": "string" }, "acceleratedPayoffDate": { "type": "string" }, "effectiveInterestReduction": { "type": "number" }, "baselineSchedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } }, "acceleratedSchedule": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "payment": { "type": "number" }, "principalPaid": { "type": "number" }, "interestPaid": { "type": "number" }, "balance": { "type": "number" }, "extraPrincipalPaid": { "type": "number" } }, "required": [ "month", "payment", "principalPaid", "interestPaid", "balance" ], "additionalProperties": false } } }, "required": [ "monthlyPI", "baselinePayoffMonths", "acceleratedPayoffMonths", "monthsSaved", "yearsSaved", "baselineTotalInterest", "acceleratedTotalInterest", "interestSaved", "totalExtraPaid", "baselinePayoffDate", "acceleratedPayoffDate", "effectiveInterestReduction" ], "additionalProperties": false } }, "required": [ "success", "calculatorId", "data" ] } } } }, "400": { "description": "Validation error — one or more input fields failed schema validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "description": "Zod flattened error object" } }, "required": [ "success", "error" ] } } } } } } }, "/health": { "get": { "operationId": "health_check", "summary": "Health check", "description": "Returns 200 when the server is reachable and healthy.", "tags": [], "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string", "maxLength": 100 } } } } } }, "404": { "description": "Not found" }, "503": { "description": "Service unavailable" } } } } } }