{"openapi":"3.1.0","info":{"title":"Retirement Atlas calculation API","version":"1.0.0","description":"Deterministic website engines. All assumptions are explicit. No entitlement decisions or transactions. API requests are processed server-side; ordinary website calculations stay browser-local. Not a Google AI Mode registration.","termsOfService":"https://retirement-atlas.pages.dev/terms/"},"servers":[{"url":"https://retirement-atlas.pages.dev"}],"paths":{"/api/v1/catalog":{"get":{"operationId":"listRetirementCalculators","summary":"List countries, models, input schemas and sources","responses":{"200":{"description":"Versioned tool catalog","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","modelVersion","countries","scope","integrationStatus"],"properties":{"apiVersion":{"type":"string"},"modelVersion":{"type":"string"},"countries":{"type":"array","items":{"type":"object","required":["country","currency","model","inputSchema","calculator","methodology","sources"]}},"scope":{"type":"string"},"integrationStatus":{"type":"string"}}}}}}}}},"/api/v1/calculate":{"post":{"operationId":"projectRetirement","summary":"Calculate one explicitly supplied scenario","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"country":{"type":"string","enum":["uk"],"description":"Product country code from the catalog; uk is the United Kingdom."},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Starting age; does not establish pension access; whole years.","minimum":55,"maximum":100},"endAge":{"type":"integer","description":"End of projection; must exceed age; whole years.","minimum":56,"maximum":110},"pot":{"type":"number","description":"Starting pension capital, GBP","minimum":0,"maximum":10000000},"monthlyWithdrawal":{"type":"number","description":"Requested gross withdrawal, GBP per month","minimum":0,"maximum":100000},"growth":{"type":"number","description":"Nominal annual investment return, percent before fees","minimum":-20,"maximum":20},"fees":{"type":"number","description":"Annual percentage fee, percent","minimum":0,"maximum":5},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":10},"increaseWithdrawals":{"type":"boolean","description":"Increase withdrawals once per year with the entered inflation."},"takeTaxFreeCash":{"type":"boolean","description":"Remove upfront tax-free cash from invested capital. That cash is not spent or reinvested by this model."},"remainingAllowance":{"type":"number","description":"Confirmed remaining standard lump sum allowance, GBP","minimum":0,"maximum":268275},"region":{"type":"string","enum":["rest","scotland"],"description":"Standard non-savings income tax region."},"otherIncome":{"type":"number","description":"Other taxable income, GBP per year in today's money","minimum":0,"maximum":1000000},"statePension":{"type":"number","description":"User-supplied State Pension forecast, GBP per year in today's money; never inferred","minimum":0,"maximum":100000},"statePensionAge":{"type":"integer","description":"User-supplied pension payment start age; whole years.","minimum":60,"maximum":100}},"required":["age","endAge","pot","monthlyWithdrawal","growth","fees","inflation","increaseWithdrawals","takeTaxFreeCash","remainingAllowance","region","otherIncome","statePension","statePensionAge"],"additionalProperties":false},"includeProjection":{"type":"boolean","description":"Optional: include annual cash-flow rows; default false. No monthly projection or alternative spending solver in API v1."}},"required":["country","input"],"additionalProperties":false},{"type":"object","properties":{"country":{"type":"string","enum":["au"],"description":"Product country code from the catalog; uk is the United Kingdom."},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Current age; whole years.","minimum":18,"maximum":100},"retirementAge":{"type":"integer","description":"Retirement age; at least current age and 60; accumulation ends by 75; whole years.","minimum":60,"maximum":100},"endAge":{"type":"integer","description":"Projection end age; must exceed retirement age; whole years.","minimum":61,"maximum":110},"balance":{"type":"number","description":"Current super balance, AUD","minimum":0,"maximum":5000000},"salary":{"type":"number","description":"Annual salary excluding super, AUD","minimum":0,"maximum":1000000},"employerRate":{"type":"number","description":"Employer contribution assumption, percent of salary; not a payroll liability calculation","minimum":0,"maximum":30},"salarySacrifice":{"type":"number","description":"Extra pre-tax contribution, AUD per month in today's money","minimum":0,"maximum":10000},"afterTax":{"type":"number","description":"After-tax contribution, AUD per month in today's money","minimum":0,"maximum":20000},"growth":{"type":"number","description":"Nominal annual return after investment earnings tax, before fees, percent","minimum":-20,"maximum":20},"fees":{"type":"number","description":"Annual percentage fee, percent","minimum":0,"maximum":5},"annualFixedFees":{"type":"number","description":"Fixed fees, AUD per year in today's money","minimum":0,"maximum":10000},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":10},"salaryGrowth":{"type":"number","description":"Nominal annual salary growth, percent","minimum":0,"maximum":10},"targetIncome":{"type":"number","description":"Target retirement spending, AUD per year in today's money","minimum":0,"maximum":500000},"agePension":{"type":"number","description":"User-supplied Age Pension estimate, AUD per year in today's money; eligibility not calculated","minimum":0,"maximum":100000},"pensionAge":{"type":"integer","description":"User-supplied Age Pension payment start age; whole years.","minimum":67,"maximum":100}},"required":["age","retirementAge","endAge","balance","salary","employerRate","salarySacrifice","afterTax","growth","fees","annualFixedFees","inflation","salaryGrowth","targetIncome","agePension","pensionAge"],"additionalProperties":false},"includeProjection":{"type":"boolean","description":"Optional: include annual cash-flow rows; default false. No monthly projection or alternative spending solver in API v1."}},"required":["country","input"],"additionalProperties":false},{"type":"object","properties":{"country":{"type":"string","enum":["nl","se","dk","no","fi","is","cz","at","ch","pt","us","cn","de","jp","in","fr","it","ca","br","ru","kr","mx","es","id","tr","sa","pl","be","ar","ie","ae","sg","il","th","nz"],"description":"Product country code from the catalog; uk is the United Kingdom."},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Current age; whole years.","minimum":18,"maximum":100},"retirementAge":{"type":"integer","description":"Work-stop age; at least current age; not an entitlement age; whole years.","minimum":18,"maximum":100},"endAge":{"type":"integer","description":"Projection end age; must exceed retirement age; whole years.","minimum":19,"maximum":110},"balance":{"type":"number","description":"Accessible savings in country currency; exclude capital behind entered pension payments","minimum":0,"maximum":1000000000000},"monthlySaving":{"type":"number","description":"Monthly savings in today's country currency","minimum":0,"maximum":1000000000},"spending":{"type":"number","description":"Monthly retirement spending in today's country currency","minimum":0,"maximum":1000000000},"netReturn":{"type":"number","description":"Nominal annual return after taxes and fees, percent; inflation is deducted by the model","minimum":-20,"maximum":100},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":100},"incomes":{"type":"array","minItems":3,"maxItems":3,"description":"Exactly three user-supplied pension streams. Use zero monthly amount for unused streams. No entitlement or tax estimation.","items":{"type":"object","properties":{"monthly":{"type":"number","description":"After-tax monthly income in today's country currency","minimum":0,"maximum":1000000000},"startAge":{"type":"integer","description":"First payment age; whole years.","minimum":18,"maximum":110},"endAge":{"type":"integer","description":"Exclusive payment stop age; use 0 for no stop, otherwise greater than startAge; whole years.","minimum":0,"maximum":110}},"required":["monthly","startAge","endAge"],"additionalProperties":false}}},"required":["age","retirementAge","endAge","balance","monthlySaving","spending","netReturn","inflation","incomes"],"additionalProperties":false},"includeProjection":{"type":"boolean","description":"Optional: include annual cash-flow rows; default false. No monthly projection or alternative spending solver in API v1."}},"required":["country","input"],"additionalProperties":false}]},"examples":{"uk":{"summary":"Synthetic arithmetic check; not a pension forecast","value":{"country":"uk","input":{"age":65,"endAge":95,"pot":300000,"monthlyWithdrawal":1000,"growth":0,"fees":0,"inflation":0,"increaseWithdrawals":false,"takeTaxFreeCash":false,"remainingAllowance":268275,"region":"rest","otherIncome":0,"statePension":0,"statePensionAge":67}}},"au":{"summary":"Synthetic arithmetic check; not a pension forecast","value":{"country":"au","input":{"age":67,"retirementAge":67,"endAge":92,"balance":300000,"salary":85000,"employerRate":12,"salarySacrifice":200,"afterTax":0,"growth":0,"fees":0,"annualFixedFees":0,"inflation":0,"salaryGrowth":2.5,"targetIncome":12000,"agePension":0,"pensionAge":67}}},"jp":{"summary":"Synthetic arithmetic check; not a pension forecast","value":{"country":"jp","input":{"age":65,"retirementAge":65,"endAge":95,"balance":36000000,"monthlySaving":0,"spending":200000,"netReturn":0,"inflation":0,"incomes":[{"monthly":100000,"startAge":65,"endAge":0},{"monthly":0,"startAge":65,"endAge":0},{"monthly":0,"startAge":65,"endAge":0}]}}}}}}},"responses":{"200":{"description":"Versioned projection, units, assumptions, limitations and source links.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["apiVersion","modelVersion","country","model","currency","input","summary","units","assumptions","limitations","warnings","sources","sourceReviewDate","calculatorUrl","methodologyUrl"],"properties":{"apiVersion":{"type":"string","const":"1.0.0"},"modelVersion":{"type":"string","const":"1.0"},"country":{"type":"string","enum":["uk"]},"model":{"type":"string","const":"uk-drawdown"},"currency":{"type":"string"},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Starting age; does not establish pension access; whole years.","minimum":55,"maximum":100},"endAge":{"type":"integer","description":"End of projection; must exceed age; whole years.","minimum":56,"maximum":110},"pot":{"type":"number","description":"Starting pension capital, GBP","minimum":0,"maximum":10000000},"monthlyWithdrawal":{"type":"number","description":"Requested gross withdrawal, GBP per month","minimum":0,"maximum":100000},"growth":{"type":"number","description":"Nominal annual investment return, percent before fees","minimum":-20,"maximum":20},"fees":{"type":"number","description":"Annual percentage fee, percent","minimum":0,"maximum":5},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":10},"increaseWithdrawals":{"type":"boolean","description":"Increase withdrawals once per year with the entered inflation."},"takeTaxFreeCash":{"type":"boolean","description":"Remove upfront tax-free cash from invested capital. That cash is not spent or reinvested by this model."},"remainingAllowance":{"type":"number","description":"Confirmed remaining standard lump sum allowance, GBP","minimum":0,"maximum":268275},"region":{"type":"string","enum":["rest","scotland"],"description":"Standard non-savings income tax region."},"otherIncome":{"type":"number","description":"Other taxable income, GBP per year in today's money","minimum":0,"maximum":1000000},"statePension":{"type":"number","description":"User-supplied State Pension forecast, GBP per year in today's money; never inferred","minimum":0,"maximum":100000},"statePensionAge":{"type":"integer","description":"User-supplied pension payment start age; whole years.","minimum":60,"maximum":100}},"required":["age","endAge","pot","monthlyWithdrawal","growth","fees","inflation","increaseWithdrawals","takeTaxFreeCash","remainingAllowance","region","otherIncome","statePension","statePensionAge"],"additionalProperties":false},"summary":{"type":"object","additionalProperties":false,"required":["initialBalance","taxFreeCash","firstYearNetMonthly","depletedAge","finalBalance"],"properties":{"initialBalance":{"type":"number","description":"GBP invested after any upfront cash removal."},"taxFreeCash":{"type":"number","description":"GBP removed at start; outside the projection."},"firstYearNetMonthly":{"type":"number","description":"First model year net income divided by 12, GBP/month."},"depletedAge":{"type":["number","null"],"description":"Age when the pot reaches zero; null means not within the selected horizon."},"finalBalance":{"type":"number","description":"Nominal GBP at endAge."}}},"units":{"type":"object","additionalProperties":{"type":"string"}},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"sourceReviewDate":{"type":"string","format":"date","description":"Historical source-context review, not a new official verification at request time."},"rulePeriod":{"type":"string"},"ruleReviewBy":{"type":"string","format":"date"},"calculatorUrl":{"type":"string","format":"uri"},"methodologyUrl":{"type":"string","format":"uri"},"projection":{"type":"object","description":"Only with includeProjection=true. Annual flows and balances; basis describes money units. Fields match the website export model.","required":["basis"],"properties":{"basis":{"type":"string"},"annual":{"type":"array","items":{"type":"object","additionalProperties":true}},"accumulation":{"type":"array","items":{"type":"object","additionalProperties":true}},"retirement":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}},{"type":"object","required":["apiVersion","modelVersion","country","model","currency","input","summary","units","assumptions","limitations","warnings","sources","sourceReviewDate","calculatorUrl","methodologyUrl"],"properties":{"apiVersion":{"type":"string","const":"1.0.0"},"modelVersion":{"type":"string","const":"1.0"},"country":{"type":"string","enum":["au"]},"model":{"type":"string","const":"au-super"},"currency":{"type":"string"},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Current age; whole years.","minimum":18,"maximum":100},"retirementAge":{"type":"integer","description":"Retirement age; at least current age and 60; accumulation ends by 75; whole years.","minimum":60,"maximum":100},"endAge":{"type":"integer","description":"Projection end age; must exceed retirement age; whole years.","minimum":61,"maximum":110},"balance":{"type":"number","description":"Current super balance, AUD","minimum":0,"maximum":5000000},"salary":{"type":"number","description":"Annual salary excluding super, AUD","minimum":0,"maximum":1000000},"employerRate":{"type":"number","description":"Employer contribution assumption, percent of salary; not a payroll liability calculation","minimum":0,"maximum":30},"salarySacrifice":{"type":"number","description":"Extra pre-tax contribution, AUD per month in today's money","minimum":0,"maximum":10000},"afterTax":{"type":"number","description":"After-tax contribution, AUD per month in today's money","minimum":0,"maximum":20000},"growth":{"type":"number","description":"Nominal annual return after investment earnings tax, before fees, percent","minimum":-20,"maximum":20},"fees":{"type":"number","description":"Annual percentage fee, percent","minimum":0,"maximum":5},"annualFixedFees":{"type":"number","description":"Fixed fees, AUD per year in today's money","minimum":0,"maximum":10000},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":10},"salaryGrowth":{"type":"number","description":"Nominal annual salary growth, percent","minimum":0,"maximum":10},"targetIncome":{"type":"number","description":"Target retirement spending, AUD per year in today's money","minimum":0,"maximum":500000},"agePension":{"type":"number","description":"User-supplied Age Pension estimate, AUD per year in today's money; eligibility not calculated","minimum":0,"maximum":100000},"pensionAge":{"type":"integer","description":"User-supplied Age Pension payment start age; whole years.","minimum":67,"maximum":100}},"required":["age","retirementAge","endAge","balance","salary","employerRate","salarySacrifice","afterTax","growth","fees","annualFixedFees","inflation","salaryGrowth","targetIncome","agePension","pensionAge"],"additionalProperties":false},"summary":{"type":"object","additionalProperties":false,"required":["nominalBalance","realBalance","totalNetContributions","levelIncome","superOnlyIncome","incomeGap","depletedAge"],"properties":{"nominalBalance":{"type":"number","description":"Nominal AUD at retirement."},"realBalance":{"type":"number","description":"Today's AUD at retirement."},"totalNetContributions":{"type":"number","description":"Nominal accumulation contributions after modelled contribution tax, AUD."},"levelIncome":{"type":"number","description":"Alternative level spending budget, today's AUD/year, before personal income tax."},"superOnlyIncome":{"type":"number","description":"Level capital-only budget, today's AUD/year."},"incomeGap":{"type":"number","description":"Entered annual target minus alternative budget, today's AUD/year; may be negative."},"depletedAge":{"type":["number","null"],"description":"Age of depletion under the entered spending target; null means not within horizon."}}},"units":{"type":"object","additionalProperties":{"type":"string"}},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"sourceReviewDate":{"type":"string","format":"date","description":"Historical source-context review, not a new official verification at request time."},"rulePeriod":{"type":"string"},"ruleReviewBy":{"type":"string","format":"date"},"calculatorUrl":{"type":"string","format":"uri"},"methodologyUrl":{"type":"string","format":"uri"},"projection":{"type":"object","description":"Only with includeProjection=true. Annual flows and balances; basis describes money units. Fields match the website export model.","required":["basis"],"properties":{"basis":{"type":"string"},"annual":{"type":"array","items":{"type":"object","additionalProperties":true}},"accumulation":{"type":"array","items":{"type":"object","additionalProperties":true}},"retirement":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}},{"type":"object","required":["apiVersion","modelVersion","country","model","currency","input","summary","units","assumptions","limitations","warnings","sources","sourceReviewDate","calculatorUrl","methodologyUrl"],"properties":{"apiVersion":{"type":"string","const":"1.0.0"},"modelVersion":{"type":"string","const":"1.0"},"country":{"type":"string","enum":["nl","se","dk","no","fi","is","cz","at","ch","pt","us","cn","de","jp","in","fr","it","ca","br","ru","kr","mx","es","id","tr","sa","pl","be","ar","ie","ae","sg","il","th","nz"]},"model":{"type":"string","const":"income-gap"},"currency":{"type":"string"},"input":{"type":"object","properties":{"age":{"type":"integer","description":"Current age; whole years.","minimum":18,"maximum":100},"retirementAge":{"type":"integer","description":"Work-stop age; at least current age; not an entitlement age; whole years.","minimum":18,"maximum":100},"endAge":{"type":"integer","description":"Projection end age; must exceed retirement age; whole years.","minimum":19,"maximum":110},"balance":{"type":"number","description":"Accessible savings in country currency; exclude capital behind entered pension payments","minimum":0,"maximum":1000000000000},"monthlySaving":{"type":"number","description":"Monthly savings in today's country currency","minimum":0,"maximum":1000000000},"spending":{"type":"number","description":"Monthly retirement spending in today's country currency","minimum":0,"maximum":1000000000},"netReturn":{"type":"number","description":"Nominal annual return after taxes and fees, percent; inflation is deducted by the model","minimum":-20,"maximum":100},"inflation":{"type":"number","description":"Annual inflation, percent","minimum":0,"maximum":100},"incomes":{"type":"array","minItems":3,"maxItems":3,"description":"Exactly three user-supplied pension streams. Use zero monthly amount for unused streams. No entitlement or tax estimation.","items":{"type":"object","properties":{"monthly":{"type":"number","description":"After-tax monthly income in today's country currency","minimum":0,"maximum":1000000000},"startAge":{"type":"integer","description":"First payment age; whole years.","minimum":18,"maximum":110},"endAge":{"type":"integer","description":"Exclusive payment stop age; use 0 for no stop, otherwise greater than startAge; whole years.","minimum":0,"maximum":110}},"required":["monthly","startAge","endAge"],"additionalProperties":false}}},"required":["age","retirementAge","endAge","balance","monthlySaving","spending","netReturn","inflation","incomes"],"additionalProperties":false},"summary":{"type":"object","additionalProperties":false,"required":["retirementBalance","requiredCapital","capitalGap","firstYearGap","shortfallAge","totalShortfall","finalBalance"],"properties":{"retirementBalance":{"type":"number","description":"Savings at retirement, today's country currency."},"requiredCapital":{"type":"number","description":"Capital needed at retirement, today's country currency."},"capitalGap":{"type":"number","description":"Additional capital needed at retirement, not a monthly contribution, today's currency."},"firstYearGap":{"type":"number","description":"Average gap per month in the first retirement year, today's currency/month."},"shortfallAge":{"type":["number","null"],"description":"Age at first unfunded month; null means not within horizon."},"totalShortfall":{"type":"number","description":"Total unfunded spending across horizon, today's currency."},"finalBalance":{"type":"number","description":"Savings at endAge, today's currency."}}},"units":{"type":"object","additionalProperties":{"type":"string"}},"assumptions":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"sourceReviewDate":{"type":"string","format":"date","description":"Historical source-context review, not a new official verification at request time."},"rulePeriod":{"type":"string"},"ruleReviewBy":{"type":"string","format":"date"},"calculatorUrl":{"type":"string","format":"uri"},"methodologyUrl":{"type":"string","format":"uri"},"projection":{"type":"object","description":"Only with includeProjection=true. Annual flows and balances; basis describes money units. Fields match the website export model.","required":["basis"],"properties":{"basis":{"type":"string"},"annual":{"type":"array","items":{"type":"object","additionalProperties":true}},"accumulation":{"type":"array","items":{"type":"object","additionalProperties":true}},"retirement":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}]}}}},"400":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"404":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"405":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"413":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"415":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"422":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"500":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}},"503":{"description":"Rejected request; no input values echoed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"}}}}}}}}}}}}}