{"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":2767,"totalInterest":330209,"costPerDollarBorrowed":1.66},"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},"termYears":{"description":"The full length of the term you signed, in years. Terms longer than five years carry a statutory penalty cap.","type":"number","minimum":1,"maximum":10,"default":5},"monthsLeft":{"description":"Months remaining in your current term","type":"number","minimum":1,"maximum":120,"default":36}}},"example":{"balance":500000,"contractRate":5.09,"currentRate":3.99,"termYears":5,"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,"termYears":5,"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. The Interest Act s.10 cap shown for terms longer than five years applies to individual borrowers and reflects the term as written; it does not apply to mortgages given by a corporation, and after January 1, 2012 it also does not apply to partnerships, business trusts or unlimited liability companies. Exercising the right requires an actual tender of principal, interest to date and three months further interest. This is general information from a mortgage brokerage, not legal advice.","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":"Buying out a co-owner reaches 95% LTV because insurers treat it as a purchase of the departing owner's interest, not as a refinance — a refinance is capped at 80% by the Bank Act. Sagen publishes this as \"Equity Buy-Out\" and Canada Guaranty as the buyout of a co-borrower's interest; both require that all parties are currently on title, and Canada Guaranty refers every such application for manual review. CMHC does not publish an equivalent policy. Insured lending is unavailable at or above $1,500,000 of property value. Because it is a purchase, the insurance premium applies to the whole new mortgage rather than only to the new money. 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":23.8},"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"}}}}}}},"/api/calculate/land-home-build-affordability":{"get":{"operationId":"get_land_home_build_affordability_schema","summary":"Schema for Land + Build Affordability","description":"Returns input/output schema and docs for the Land + Home Build Affordability Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_land_home_build_affordability","summary":"Land + Home Build Affordability Calculator","description":"Add up cheap land, a factory-built or modular home, and servicing into one all-in project cost, then see the monthly mortgage payment — and how it compares to a typical big-city home. Uses Canadian semi-annual compounding.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"landCost":{"description":"Price of the serviced (or to-be-serviced) lot in CAD","type":"number","minimum":0,"maximum":1000000,"default":60000},"homeCost":{"description":"Cost of the factory-built or modular home, delivered","type":"number","minimum":20000,"maximum":600000,"default":120000},"servicingCost":{"description":"Foundation, utility hookups, permits, and site prep","type":"number","minimum":0,"maximum":200000,"default":20000},"downPayment":{"description":"Cash you put down (or lot equity if you already own the land)","type":"number","minimum":0,"maximum":1000000,"default":10000},"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":30},"comparisonHomePrice":{"description":"A typical big-city home price to compare against (e.g. Metro Vancouver)","type":"number","minimum":100000,"maximum":3000000,"default":600000}}},"example":{"landCost":60000,"homeCost":120000,"servicingCost":20000,"downPayment":10000,"annualRate":4.5,"amortizationYears":30,"comparisonHomePrice":600000}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"land-home-build-affordability","inputs":{"landCost":60000,"homeCost":120000,"servicingCost":20000,"downPayment":10000,"annualRate":4.5,"amortizationYears":30,"comparisonHomePrice":600000},"result":{"totalProjectCost":200000,"mortgageAmount":190000,"monthlyPayment":958,"comparisonMonthlyPayment":3025},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/land-home-build-affordability","disclaimer":"Figures are illustrative estimates, not a quote. Land prices, modular-home costs, servicing, rates, and lender policies on modular/self-build financing vary widely. CMHC insurance is not applied — its treatment of modular and self-build homes varies by insurer and lender. Calculations use Canadian semi-annual compounding per the Bank Act. Consult a licensed mortgage professional.","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/secondary-suite-refinance":{"get":{"operationId":"get_secondary_suite_refinance_schema","summary":"Schema for Secondary Suite Refinance","description":"Returns input/output schema and docs for the Secondary Suite Refinance Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_secondary_suite_refinance","summary":"Secondary Suite Refinance Calculator","description":"The $80K federal suite loan was never implemented — this is the program that actually exists. Model an insured refinance up to 90% of your home's post-renovation value (capped below $2M, 30-year amortization) to build a legal secondary suite, including the CMHC premium and the Multigenerational Home Renovation Tax Credit.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"homeValue":{"description":"Your home's current market value in CAD","type":"number","minimum":200000,"maximum":2500000,"default":600000},"mortgageBalance":{"description":"Outstanding balance on your existing mortgage","type":"number","minimum":0,"maximum":1900000,"default":470000},"renoCost":{"description":"Estimated cost to build the legal secondary suite","type":"number","minimum":10000,"maximum":500000,"default":175000},"annualRate":{"description":"Stated annual interest rate for the refinanced mortgage","type":"number","minimum":0.5,"maximum":15,"default":4.5},"amortizationYears":{"description":"Amortization period — the program allows up to 30 years","type":"string","enum":["25","30"],"default":"30"},"mhrtcEligible":{"description":"The Multigenerational Home Renovation Tax Credit only applies when the suite houses a senior (65+) or a family member eligible for the Disability Tax Credit","type":"boolean","default":false}}},"example":{"homeValue":600000,"mortgageBalance":470000,"renoCost":175000,"annualRate":4.5,"amortizationYears":"30","mhrtcEligible":true}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"secondary-suite-refinance","inputs":{"homeValue":600000,"mortgageBalance":470000,"renoCost":175000,"annualRate":4.5,"amortizationYears":"30","mhrtcEligible":true},"result":{"postRenoValue":775000,"maxInsuredLoan":697500,"newLoanAmount":645000,"fundsUnlocked":175000,"ltv":83.2,"cmhcPremiumRate":6.4,"cmhcPremium":11200,"totalNewMortgage":656200,"monthlyPayment":3309,"mhrtcCredit":7500},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/secondary-suite-refinance","disclaimer":"Estimates only, not a quote. Post-renovation value is assumed to equal current value plus construction cost — your lender's appraisal may differ, which changes the numbers. Premiums follow CMHC's published homeowner refinance schedule (lesser of premium on total loan or on the increase, plus 0.20% beyond 25-year amortization); provincial sales tax on the premium is not included. The property's as-improved value must be below $2M, one unit must be owner- or family-occupied, and the suite must be a legal, self-contained long-term rental. Breaking a fixed mortgage mid-term may trigger a prepayment penalty not modeled here. The MHRTC requires the suite to house a senior (65+) or DTC-eligible family member. All payments use Canadian semi-annual compounding per the Bank Act. Consult a licensed mortgage professional.","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/gst-rebate-mortgage-impact":{"get":{"operationId":"get_gst_rebate_mortgage_impact_schema","summary":"Schema for GST Rebate Mortgage Impact","description":"Returns input/output schema and docs for the GST Rebate Mortgage Impact Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_gst_rebate_mortgage_impact","summary":"GST Rebate Mortgage Impact Calculator","description":"Bill C-4's federal GST rebate (up to $50,000, first-time buyers, new construction) can lower the price you actually finance. Model how a builder-credited rebate changes your loan-to-value, your CMHC insurance tier, and your monthly payment — not just your tax bill.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purchasePrice":{"description":"The new-construction purchase price on your agreement, before any GST rebate is applied","type":"number","minimum":200000,"maximum":1500000,"default":700000},"gstRebateAmount":{"description":"Confirm this with your builder or accountant — a simplified estimate is 5% of price up to $1M, tapering to $0 at $1.5M, capped at $50,000","type":"number","minimum":0,"maximum":50000,"default":35000},"rebateAssignedToBuilder":{"description":"True if the builder reduces the amount owing on the statement of adjustments (the standard path since March 12, 2026). False if you claim the rebate yourself from CRA after closing — in that case the rebate is separate cash and does not change your mortgage.","type":"boolean","default":true},"downPaymentAmount":{"description":"Cash down payment in dollars, unchanged by the rebate","type":"number","minimum":10000,"maximum":750000,"default":66500},"annualRate":{"description":"Stated annual interest rate","type":"number","minimum":0.5,"maximum":15,"default":4.5},"amortizationYears":{"description":"30-year insured amortization is available to first-time buyers purchasing a newly built home","type":"string","enum":["25","30"],"default":"30"},"isFirstTimeBuyer":{"description":"Required for both the federal GST rebate and the 30-year insured amortization option","type":"boolean","default":true}}},"example":{"purchasePrice":700000,"gstRebateAmount":35000,"rebateAssignedToBuilder":true,"downPaymentAmount":66500,"annualRate":4.5,"amortizationYears":"30","isFirstTimeBuyer":true}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"gst-rebate-mortgage-impact","inputs":{"purchasePrice":700000,"gstRebateAmount":35000,"rebateAssignedToBuilder":true,"downPaymentAmount":66500,"annualRate":4.5,"amortizationYears":"30","isFirstTimeBuyer":true},"result":{"effectivePrice":665000,"ltvBefore":90.5,"ltvAfter":90,"cmhcPremiumRateBefore":4.2,"cmhcPremiumRateAfter":3.3,"tierShifted":true},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/gst-rebate-mortgage-impact","disclaimer":"Estimates only, not a quote. The GST rebate amount should be confirmed with your builder or accountant — this tool does not calculate the rebate itself, only its effect on your mortgage once you enter it. Whether the rebate reduces your financed amount depends entirely on how your specific agreement of purchase and sale is structured; ask your builder directly. CMHC premium tiers include the 0.20% surcharge for first-time buyers using 30-year amortization. All payments use Canadian semi-annual compounding per the Bank Act. Consult a licensed mortgage professional before relying on these numbers.","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/refinance-headroom":{"get":{"operationId":"get_refinance_headroom_schema","summary":"Schema for Refinance Headroom","description":"Returns input/output schema and docs for the Refinance Headroom Calculator calculator.","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Calculator schema","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"calculate_refinance_headroom","summary":"Refinance Headroom Calculator","description":"Find out how much you can actually refinance in Canada, and which limit stops you first — the 80% loan-to-value ceiling in the Bank Act, or your income under the stress test. Also shows whether one of the two named insured paths above 80% is open to you.","tags":["Calculators"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"homeValue":{"description":"Current market value of the property","type":"number","minimum":100000,"maximum":5000000,"default":800000},"mortgageBalance":{"description":"Outstanding balance on your existing mortgage","type":"number","minimum":0,"maximum":5000000,"default":560000},"grossAnnualIncome":{"description":"Combined annual household income before tax","type":"number","minimum":20000,"maximum":1000000,"default":150000},"monthlyDebts":{"description":"Car loans, credit cards, lines of credit, student loans — everything except this mortgage","type":"number","minimum":0,"maximum":20000,"default":700},"annualPropertyTax":{"description":"Yearly municipal property tax","type":"number","minimum":0,"maximum":60000,"default":5200},"monthlyHeat":{"description":"Estimated monthly heating cost, which lenders include in the debt service ratios","type":"number","minimum":0,"maximum":2000,"default":150},"rate":{"description":"Expected contract rate on the new mortgage","type":"number","minimum":0.5,"maximum":15,"default":4.49},"amortizationYears":{"description":"Amortization period in years","type":"number","minimum":5,"maximum":30,"default":25},"goal":{"description":"The purpose decides whether any insured path above 80% exists at all","type":"string","enum":["cash-out","debt-consolidation","add-suite","buy-out-co-owner"],"default":"cash-out"},"renoCost":{"description":"Only used when the goal is building a legal secondary suite","type":"number","minimum":0,"maximum":1000000,"default":0}}},"example":{"homeValue":800000,"mortgageBalance":560000,"grossAnnualIncome":150000,"monthlyDebts":700,"annualPropertyTax":5200,"monthlyHeat":150,"rate":4.49,"amortizationYears":25,"goal":"cash-out","renoCost":0}}}},"responses":{"200":{"description":"Calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"},"example":{"calculator":"refinance-headroom","inputs":{"homeValue":800000,"mortgageBalance":560000,"grossAnnualIncome":150000,"monthlyDebts":700,"annualPropertyTax":5200,"monthlyHeat":150,"rate":4.49,"amortizationYears":25,"goal":"cash-out","renoCost":0},"result":{"insuredPathAvailable":false},"source":"Mortgages Lab","sourceUrl":"https://mortgageslab.ca/calculators/refinance-headroom","disclaimer":"Estimates only, not a quote or an approval. The 80% conventional refinance ceiling is statutory (Bank Act s.418(1)); the paths above it are insurer programs whose terms change and whose availability varies by lender. GDS 39% and TDS 44% are the insured-mortgage limits — some lenders apply tighter ratios, and uninsured lending policy varies. Condominium fees (lenders typically count 50%) and secondary-suite rental income offsets are not modelled here, and both can move your ratios materially. The equity buy-out path exceeds 80% because it is structured as a purchase transaction, not a refinance. All payments use Canadian semi-annual compounding per the Bank Act. Confirm your numbers with a licensed mortgage professional.","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"}]}