Retirement calculation API documentation

Request: POST /api/retirement/calculate

Use this website’s origin with the path above. Content-Type must be application/json (optionally charset=utf-8). Maximum UTF-8 body size: 8,192 bytes. All fields are required numbers, with no silent defaults and no extra fields. Money and ages are whole numbers; rates are annual percentages. Retirement age must be at least current age and the horizon must be greater than retirement age. See the complete input bounds and units.

{
  "age": 35,
  "retirementAge": 60,
  "lifeExpectancy": 90,
  "monthlyExpense": 50000,
  "currentSavings": 1000000,
  "monthlySavings": 20000,
  "inflation": 6,
  "preReturn": 10,
  "postReturn": 6,
  "withdrawalTaxPercent": 5
}

For example, assign this site’s HTTPS origin to SITE_ORIGIN in your terminal, then submit the fictional example:

curl --fail-with-body "$SITE_ORIGIN/api/retirement/calculate" \
  -H 'Content-Type: application/json' \
  --data '{"age":35,"retirementAge":60,"lifeExpectancy":90,"monthlyExpense":50000,"currentSavings":1000000,"monthlySavings":20000,"inflation":6,"preReturn":10,"postReturn":6,"withdrawalTaxPercent":5}'

Never put financial values in query strings. Do not send saved plans, names, account records, attachments or authentication cookies. GET does not perform calculations. The page calculator itself continues to run locally; this service is an optional separate interface for explicitly submitted inputs.

Response contract, version 1

Download the OpenAPI 3.1 specification. Success returns HTTP 200 and application/json. All amounts are nominal INR, not today’s purchasing power at every age. The response is not cached. The following summary is calculated from the exact fictional request above; no personal data is used.

{
  "contractVersion": "1",
  "currency": "INR",
  "target": 81319655.74250817,
  "requiredCorpus": 81319655.74250817,
  "projected": 34438000.20752052,
  "gap": 46881655.53498765,
  "monthlyTarget": 59724.68,
  "requiredMonthlySIP": 59724.68,
  "retirementExpense": 2575122.431846093,
  "readiness": 42.34892522979382,
  "years": 25,
  "assumptions": {
    "monetaryBasis": "nominal-INR",
    "rateUnit": "annual-percentage",
    "inflationPercent": 6,
    "preRetirementReturnPercent": 10,
    "postRetirementReturnPercent": 6,
    "effectiveWithdrawalTaxPercent": 5,
    "returnsNetOfFeesAndInvestmentTaxes": true,
    "contributionTiming": "year-end",
    "contributionGrowthPercent": 0,
    "contributionAggregation": "monthly-amount-times-12",
    "retirementSpendingTiming": "year-start",
    "horizonEndAgeExclusive": 90,
    "projectionBasis": "supplied-current-savings-and-monthly-savings",
    "requiredMonthlySIPMeaning": "total-constant-monthly-equivalent-not-monthly-compounding",
    "requiredMonthlySIPRounding": "up-to-0.01-INR"
  },
  "limitations": [
    {
      "code": "ILLUSTRATIVE_ONLY",
      "message": "Educational deterministic estimate, not investment or tax advice; returns and inflation are assumptions, not forecasts."
    },
    {
      "code": "NO_MONTHLY_COMPOUNDING",
      "message": "requiredMonthlySIP aliases monthlyTarget: twelve monthly amounts are contributed at each year end, not invested monthly."
    },
    {
      "code": "NO_MARKET_RISK_MODEL",
      "message": "No volatility, sequence-of-returns simulation or probability of success; readiness is a capped funding ratio."
    },
    {
      "code": "SIMPLIFIED_TAX_AND_ACCESS",
      "message": "Withdrawal tax is an illustrative effective gross-up, not statutory taxation; no scheme-specific access or liquidity rules."
    },
    {
      "code": "EXCLUDED_CASH_FLOWS",
      "message": "No pension income, individual accounts, family events, salary growth, spending changes or borrowing."
    },
    {
      "code": "IMMEDIATE_RETIREMENT",
      "message": "When retiring now, monthlyTarget and requiredMonthlySIP are zero; gap is the immediate capital shortfall."
    }
  ]
}

requiredCorpus / target

Capital needed at retirement, before the first start-of-year withdrawal.

requiredMonthlySIP / monthlyTarget

Total constant monthly saving needed, rounded up to a paisa. These aliases aggregate twelve contributions at each year end; they do not model a monthly-compounding SIP. Zero when retiring immediately: check gap instead.

projected, gap and readiness

Projected retirement savings at the supplied contribution; nonnegative capital shortfall; funding percentage capped at 100, not success probability.

retirementExpense and years

Annual spending in the first retirement year, before withdrawal tax; whole saving years until retirement.

yearlyProjections

One row for each age from current age through horizon minus one, following supplied contributions—not the required minimum. year is a zero-based offset, not a calendar year. phase is accumulation or retirement. Balances are nominal INR.

Annual cash-flow fields

openingBalance; contribution; expense (retirement net spending need); requiredWithdrawal (gross need); withdrawal (gross amount actually funded); withdrawalTax; netSpending (funded expenses); shortfall; investmentReturn; closingBalance. The methodology defines every recurrence and timing convention.

assumptions and limitations

Applied rates, horizon, contribution and spending timing, rounding, projection basis and warnings. Agents should preserve these disclosures rather than present estimates as guarantees.

First annual row for the example

{
  "age": 35,
  "year": 0,
  "phase": "accumulation",
  "openingBalance": 1000000,
  "contribution": 240000,
  "expense": 0,
  "requiredWithdrawal": 0,
  "withdrawal": 0,
  "withdrawalTax": 0,
  "netSpending": 0,
  "shortfall": 0,
  "investmentReturn": 100000,
  "closingBalance": 1340000
}

Errors and rate limits

Errors have a contractVersion and an error object containing code, message and documentation. Invalid JSON, inputs or query strings return 400; non-POST methods 405 with Allow: POST; oversized bodies 413; unsupported media types or compression 415; throttling 429 with Retry-After seconds; unexpected application failures 500. Platform failures may use a different response format. Do not retry invalid inputs automatically.

Abuse protection is best-effort, in-memory and per worker: 60 requests per fixed minute per trusted client bucket and 300 attempts per worker. The current managed host provides no verified connection-IP interface to this handler, so all callers share the conservative 60-request fallback bucket on each worker. Forwarded IP headers cannot bypass it. Restarts reset counters and multiple workers have separate budgets; this is not a distributed quota or a production DDoS guarantee. Honour Retry-After and use bounded retries.

Privacy and agent integration

The service computes only the submitted numbers. Application code does not retain financial payloads or log request/response bodies, access browser plans or use a database. Short-lived counters are used for throttling; verified IPs, if a supported host adapter is later supplied, are hashed with an ephemeral worker salt. Host infrastructure may retain ordinary access metadata; see privacy disclosures. Query strings are rejected but could still enter host access logs, so never send inputs there.

This public endpoint can be configured as an explicit agent tool using the OpenAPI contract. Publishing it, allowing OAI-SearchBot and providing llms.txt do not guarantee that ChatGPT will discover, cite or invoke it. There is no installed ChatGPT app or connector in this release. No cross-origin browser access is enabled by the application.