{"openapi":"3.1.0","info":{"title":"Mortgages Lab Calculator API","version":"1.0.0","description":"Production-grade Canadian mortgage calculators accessible via JSON API. All calculations use semi-annual compounding per the Bank Act. Includes CMHC insurance, stress test, land transfer tax, IRD penalty, and more.","contact":{"name":"Mortgages Lab","url":"https://mortgageslab.ca/developers","email":"camilo@mortgageslab.ca"},"license":{"name":"Proprietary — see Terms of Use","url":"https://mortgageslab.ca/developers#terms"}},"servers":[{"url":"https://mortgageslab.ca","description":"Production"}],"security":[{"ApiKeyHeader":[]}],"paths":{"/api/calculators":{"get":{"operationId":"listCalculators","summary":"List all available calculators","description":"Returns all calculators with their input/output schemas and examples.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator listing","content":{"application/json":{"schema":{"type":"object","properties":{"totalCalculators":{"type":"integer"},"calculators":{"type":"array","items":{"$ref":"#/components/schemas/CalculatorSummary"}}}}}}}}}},"/api/calculate/cmhc-insurance":{"get":{"operationId":"get_cmhc_insurance_schema","summary":"Schema for CMHC Insurance","description":"Returns input/output schema and docs for the CMHC Insurance Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_cmhc_insurance","summary":"CMHC Insurance Calculator","description":"Compare 19% down (insured, lower rate) vs 20% down (uninsured) to see which strategy saves you more over 5 years. Uses Canadian semi-annual compounding.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"homePrice":{"description":"Purchase price of the home in CAD","type":"number","minimum":200000,"maximum":1500000,"default":700000},"insuredRate":{"description":"Mortgage rate for insured mortgages (< 20% down)","type":"number","minimum":0.5,"maximum":15,"default":4.29},"uninsuredRate":{"description":"Mortgage rate for uninsured mortgages (>= 20% down)","type":"number","minimum":0.5,"maximum":15,"default":4.64}}},"example":{"homePrice":700000,"insuredRate":4.29,"uninsuredRate":4.64}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"cmhc-insurance","inputs":{"homePrice":700000,"insuredRate":4.29,"uninsuredRate":4.64},"result":{"insuredDownPayment":133000,"cmhcPremiumRate":2.8,"insuredMonthlyPayment":3089,"uninsuredMonthlyPayment":3162},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/cmhc-insurance","disclaimer":"Rates shown are illustrative. CMHC premiums based on current official tiers. Your actual rates will vary by lender, credit score, and market conditions. All calculations use Canadian semi-annual compounding per the Bank Act.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calculate/cost-of-borrowing":{"get":{"operationId":"get_cost_of_borrowing_schema","summary":"Schema for Cost of Borrowing","description":"Returns input/output schema and docs for the Cost of Borrowing Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_cost_of_borrowing","summary":"Cost of Borrowing Calculator","description":"See the true cost of your mortgage: total interest paid, effective annual rate, cost per dollar borrowed, and how a 1% rate change impacts your bottom line. Uses Canadian semi-annual compounding.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"principal":{"description":"Total mortgage principal in CAD","type":"number","minimum":50000,"maximum":5000000,"default":500000},"annualRate":{"description":"Stated annual interest rate","type":"number","minimum":0.5,"maximum":15,"default":4.5},"amortizationYears":{"description":"Amortization period in years","type":"number","minimum":5,"maximum":30,"default":25}}},"example":{"principal":500000,"annualRate":4.5,"amortizationYears":25}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"cost-of-borrowing","inputs":{"principal":500000,"annualRate":4.5,"amortizationYears":25},"result":{"monthlyPayment":2728,"totalInterest":318302,"costPerDollarBorrowed":1.64},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/cost-of-borrowing","disclaimer":"Calculation uses Canadian semi-annual compounding per the Bank Act. Actual costs may vary with prepayments, rate changes at renewal, and lender fees.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calculate/ird-penalty":{"get":{"operationId":"get_ird_penalty_schema","summary":"Schema for IRD Penalty","description":"Returns input/output schema and docs for the IRD Penalty Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_ird_penalty","summary":"IRD Penalty Calculator","description":"Calculate your Interest Rate Differential (IRD) penalty for breaking a fixed mortgage early. Shows the penalty amount, breakeven timeline, and whether switching lenders actually saves you money.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"description":"Current outstanding mortgage balance","type":"number","minimum":50000,"maximum":3000000,"default":500000},"contractRate":{"description":"Your existing mortgage rate","type":"number","minimum":0.5,"maximum":15,"default":5.09},"currentRate":{"description":"The rate you could get by switching","type":"number","minimum":0.5,"maximum":15,"default":3.99},"monthsLeft":{"description":"Months remaining in your current term","type":"number","minimum":1,"maximum":60,"default":36}}},"example":{"balance":500000,"contractRate":5.09,"currentRate":3.99,"monthsLeft":36}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"ird-penalty","inputs":{"balance":500000,"contractRate":5.09,"currentRate":3.99,"monthsLeft":36},"result":{"penaltySource":"IRD","worthIt":false},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/ird-penalty","disclaimer":"This uses a simplified IRD formula. Big 5 banks use a posted-rate formula that typically produces a higher penalty. Request the exact calculation from your lender before making a decision.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calculate/spousal-buyout":{"get":{"operationId":"get_spousal_buyout_schema","summary":"Schema for Spousal Buyout","description":"Returns input/output schema and docs for the Spousal Buyout Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_spousal_buyout","summary":"Spousal Buyout Calculator","description":"Calculate how much you need to borrow to keep the home in a separation — including your ex's equity payout, debt consolidation, CMHC insurance, and stress test qualification.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"homeValue":{"description":"Current market value of the property","type":"number","minimum":200000,"maximum":3000000,"default":700000},"mortgageBalance":{"description":"Remaining mortgage on the property","type":"number","minimum":0,"maximum":3000000,"default":400000},"exEquityPercent":{"description":"Percentage of equity owed to ex-spouse","type":"number","minimum":0,"maximum":100,"default":50},"debtsToConsolidate":{"description":"Joint debts to consolidate into the new mortgage","type":"number","minimum":0,"maximum":500000,"default":25000},"rate":{"description":"Expected mortgage interest rate","type":"number","minimum":2,"maximum":10,"default":4.89},"amortizationYears":{"description":"Amortization period in years","type":"number","minimum":15,"maximum":30,"default":25}}},"example":{"homeValue":700000,"mortgageBalance":400000,"exEquityPercent":50,"debtsToConsolidate":25000,"rate":4.89,"amortizationYears":25}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"spousal-buyout","inputs":{"homeValue":700000,"mortgageBalance":400000,"exEquityPercent":50,"debtsToConsolidate":25000,"rate":4.89,"amortizationYears":25},"result":{"equityToEx":150000,"needsInsurance":true},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/spousal-buyout","disclaimer":"The Spousal Buyout Program caps at 95% LTV. Property value limits apply: $1.5M for insured mortgages. Speak with a mortgage broker for your specific situation.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calculate/renewal-shock":{"get":{"operationId":"get_renewal_shock_schema","summary":"Schema for Renewal Shock","description":"Returns input/output schema and docs for the Renewal Payment Shock Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_renewal_shock","summary":"Renewal Payment Shock Calculator","description":"See exactly how your mortgage renewal rate change affects monthly payments, annual costs, and 5-year impact. Includes an amortization extension relief scenario.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"description":"Current mortgage balance at renewal","type":"number","minimum":50000,"maximum":2000000,"default":400000},"oldRate":{"description":"Your current mortgage rate about to expire","type":"number","minimum":0.5,"maximum":10,"default":1.89},"newRate":{"description":"The rate you expect at renewal","type":"number","minimum":0.5,"maximum":10,"default":4.29},"remainingAmort":{"description":"Years remaining on your amortization","type":"number","minimum":5,"maximum":30,"default":20}}},"example":{"balance":400000,"oldRate":1.89,"newRate":4.29,"remainingAmort":20}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"renewal-shock","inputs":{"balance":400000,"oldRate":1.89,"newRate":4.29,"remainingAmort":20},"result":{"percentIncrease":30.5},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/renewal-shock","disclaimer":"Calculations use Canadian semi-annual compounding. Actual renewal rates depend on your creditworthiness, lender, and market conditions at time of renewal.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/calculate/skip-payment":{"get":{"operationId":"get_skip_payment_schema","summary":"Schema for Skip Payment","description":"Returns input/output schema and docs for the Skip-a-Payment True Cost Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_skip_payment","summary":"Skip-a-Payment True Cost Calculator","description":"See the real cost of skipping mortgage payments. Interest keeps compounding while you pause — this calculator shows the added balance, increased payments, and extra months on your mortgage.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"description":"Current mortgage balance","type":"number","minimum":50000,"maximum":2000000,"default":400000},"rate":{"description":"Your current mortgage rate","type":"number","minimum":1,"maximum":10,"default":4.79},"remainingAmort":{"description":"Years remaining on your amortization","type":"number","minimum":1,"maximum":30,"default":22},"skippedMonths":{"description":"Number of payments to skip","type":"number","minimum":1,"maximum":6,"default":3}}},"example":{"balance":400000,"rate":4.79,"remainingAmort":22,"skippedMonths":3}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"skip-payment","inputs":{"balance":400000,"rate":4.79,"remainingAmort":22,"skippedMonths":3},"result":{},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/skip-payment","disclaimer":"Interest compounds during skipped months. Most lenders add accrued interest to your principal. Uses Canadian semi-annual compounding.","calculatedAt":"2026-05-14T12:00:00.000Z"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for higher rate limits. Get one at https://mortgageslab.ca/developers#register"}},"schemas":{"CalculatorSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"endpoint":{"type":"string"}}},"CalculateResponse":{"type":"object","properties":{"calculator":{"type":"string"},"inputs":{"type":"object"},"result":{"type":"object"},"source":{"type":"string","example":"Mortgages Lab"},"sourceUrl":{"type":"string","format":"uri"},"disclaimer":{"type":"string"},"calculatedAt":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"tags":[{"name":"Discovery","description":"Endpoints for discovering available calculators"},{"name":"Calculators","description":"Execute mortgage calculations"}]}