firenum Fire Plan API

openapi: 3.2.0
info:
  title: firenum.com Agent Fire Plan API
  version: 1.4.2
  description: 'Turns what someone has said about their money into firenum''s answer and their plan in firenum''s Fire Planner

    (FIRE: Financial Independence, Retire Early). The answer is the planner''s own, as their plan shows it once

    opened: when they can retire with their contributions, growth and inflation, graded three ways (average returns,

    500 Monte Carlo simulations, every historical start year since 1872). For a FIRE number it gives the number and,

    once it has their age, when they would reach it. All parameters are optional: with too little to grade,

    `missing` says what to ask for.


    Reply from `answer`. Give the headline with both counts: the headline''s date is the first month the money lasts on

    average returns, and the counts say how often that survives real market swings. When a count is under half, open

    with that count ("The money lasts in only N of 500 simulated markets"), never with yes, even a qualified one ("on

    average returns, yes", "a risky yes"): the date works on average but fails in most markets. `coast_number` is

    their Coast FIRE number for `coast_age` (what they would need invested today to stop saving). `coast` is the

    planner''s own answer to stopping saving today: whether the money still lasts if they retire on the headline''s date

    and, if not, the date that works without more saving. `assumed`, when present, is what the answer took for

    something they didn''t say: say so in those terms. `missing` is what the planner needs before it can grade

    anything: ask for it and call again. To grade another retirement year, call again with `retire`. Amounts are in

    their currency, sums in today''s money. `table` is their net worth year by year on each model, with income,

    spending and withdrawals, and `assumptions` is what the answer rests on (the rates, how each model works, how

    their numbers were read, what is not modeled): answer follow-ups from them (what they would have at 60, when the

    money runs out in a bad market, why a date) without calling again, and say what an answer assumes when it matters.


    Give them the returned url exactly as it is: it opens their plan, the whole planner (stress tests, a year-by-year

    table, where the money goes), as a new plan, "From a link", beside any plans they have. A link without an age,

    spending or income opens the quick-start with these numbers filled in instead, and asks for the rest. Without

    `source=agent` the planner opens it as a shared plan that saves nothing. It runs in their browser with no account. The plan keeps the accounts,

    spending lines, debts, pension, Social Security and rental income sent. Salary and side income become one monthly

    income.


    Income is annual. Expenses and contributions are monthly. Amounts in whole currency units (not cents). Growth and

    inflation are percentages.


    Taxes are off by default, in any country: income is take-home pay. For someone in the US who gives income before

    tax, send `taxes=us` (and `state`, a partner, dependents, their Social Security statement figure and a Roth

    conversion strategy when they say them): the planner then computes federal, state and payroll tax every year, and

    the table gains each year''s tax. Amounts are then dollars.


    Before retirement, any spending, debt payments and contributions that income doesn''t cover are paid from savings.

    Without `salary` or `side_income`, and with retirement still ahead, the answer assumes an income that covers

    spending, contributions and debt payments until then (`assumed` says so), and the quick-start asks for it.'
servers:
- url: https://firenum.com
tags:
- name: Fire Plan
paths:
  /api/fire-plan:
    post:
      operationId: build_retirement_plan
      summary: Build a retirement plan
      description: 'Use when someone asks when they can retire, if their money will last, their FIRE number (the planner shows when

        they''d reach it), or about Coast, Barista, Lean or Fat FIRE, and gave numbers (age, income, savings, spending,

        debts). Send what they gave, as said. Returns its answer and plan link.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                birth:
                  type: integer
                  example: 1990
                  description: Birth year (YYYY). From an age, send the current year minus the age. Used with retire_age to compute retirement date.
                retire:
                  type: integer
                  example: 2045
                  description: Target retirement year (YYYY). Takes precedence over retire_age.
                retire_age:
                  type: integer
                  example: 55
                  description: Target retirement age. Requires birth to compute retirement year. Ignored if retire is provided.
                currency:
                  type: string
                  enum:
                  - USD
                  - EUR
                  - GBP
                  - JPY
                  - CAD
                  - AUD
                  - CHF
                  - INR
                  - NZD
                  default: USD
                  description: Display currency. All amounts should be in this currency.
                retirement:
                  type: number
                  example: 200000
                  description: Retirement account balance (401k, IRA, etc). Default growth 7%.
                retirement_contribution:
                  type: number
                  example: 1500
                  description: Monthly retirement account contribution.
                roth:
                  type: number
                  example: 50000
                  description: Roth account balance (Roth IRA, Roth 401k). Default growth 7%.
                roth_contribution:
                  type: number
                  example: 500
                  description: Monthly Roth account contribution.
                brokerage:
                  type: number
                  example: 100000
                  description: Taxable brokerage account balance. Default growth 7%.
                brokerage_contribution:
                  type: number
                  example: 500
                  description: Monthly brokerage contribution.
                savings:
                  type: number
                  example: 20000
                  description: High-yield savings balance. Default growth 4.5%.
                savings_contribution:
                  type: number
                  example: 200
                  description: Monthly savings contribution.
                hsa:
                  type: number
                  example: 15000
                  description: Health Savings Account balance. Default growth 7%.
                hsa_contribution:
                  type: number
                  example: 300
                  description: Monthly HSA contribution.
                cash:
                  type: number
                  example: 5000
                  description: Cash/checking balance. Default growth 0%.
                cash_contribution:
                  type: number
                  example: 0
                  description: Monthly cash contribution.
                real_estate:
                  type: number
                  example: 300000
                  description: Real estate equity. Default growth 4%.
                real_estate_contribution:
                  type: number
                  example: 0
                  description: Monthly real estate contribution (e.g., extra mortgage principal).
                crypto:
                  type: number
                  example: 10000
                  description: Cryptocurrency balance. Default growth 0%.
                crypto_contribution:
                  type: number
                  example: 100
                  description: Monthly crypto contribution.
                salary:
                  type: number
                  example: 80000
                  description: Annual gross salary, as they said it (don't subtract tax). Grows 3%/year, stops at retirement (open-ended if no retirement date is given). The planner doesn't deduct taxes; if they gave a tax amount, include it in expenses.
                side_income:
                  type: number
                  example: 12000
                  description: Annual side hustle / freelance income. Stops at retirement (open-ended if no retirement date is given).
                part_time_income:
                  type: number
                  example: 18000
                  description: Annual part-time income in retirement (Barista FIRE). Starts at the retirement date and runs on; with no retirement date given, the plan retires at the earliest date that works with this income.
                part_time_until:
                  type: integer
                  minimum: 30
                  maximum: 100
                  example: 60
                  description: Age part_time_income stops (needs birth). Omitted or 100 = for life.
                pension:
                  type: number
                  example: 24000
                  description: Annual pension income. Starts at retirement (immediately if no retirement date is given).
                social_security:
                  type: number
                  example: 20000
                  description: Annual Social Security income. Starts at claim_age when sent with birth; otherwise at the later of retirement and age 67 (uses whichever is known; immediately if neither).
                rental_income:
                  type: number
                  example: 18000
                  description: Annual rental income.
                expenses:
                  type: number
                  example: 4000
                  description: Total monthly spending. Send this alone, or categories alone. If both are sent, categories count as part of this total and only the remainder becomes "Monthly expenses" (never added on top). Do not repeat the total as a category.
                housing:
                  type: number
                  example: 1800
                  description: Monthly housing expense (rent/mortgage).
                healthcare:
                  type: number
                  example: 300
                  description: Monthly healthcare expense.
                food:
                  type: number
                  example: 600
                  description: Monthly food expense.
                transportation:
                  type: number
                  example: 400
                  description: Monthly transportation expense.
                utilities:
                  type: number
                  example: 200
                  description: Monthly utilities expense.
                insurance:
                  type: number
                  example: 300
                  description: Monthly insurance expense.
                discretionary:
                  type: number
                  example: 500
                  description: Monthly discretionary spending.
                debt:
                  type: number
                  example: 25000
                  description: Debt balance.
                debt_rate:
                  type: number
                  example: 5.5
                  description: Debt annual interest rate (percentage).
                debt_payment:
                  type: number
                  example: 400
                  description: Monthly debt payment.
                debt_name:
                  type: string
                  example: Student Loan
                  description: Name/label for the debt. Default "Debt".
                target:
                  type: number
                  example: 1200000
                  description: Accepted from older links and ignored. The planner answers with a retirement date, not a target.
                growth:
                  type: number
                  default: 7
                  example: 6
                  description: Default portfolio growth rate (percentage). Retirement, Roth, brokerage and HSA balances follow it as the market rate (randomized in Monte Carlo, historical in backtests); it also overrides the fixed defaults of the other assets.
                inflation:
                  type: number
                  default: 3
                  example: 4
                  description: Default inflation rate (percentage). Overrides individual expense defaults.
                taxes:
                  type: string
                  enum:
                  - us
                  - 'off'
                  default: 'off'
                  description: '"us" computes US federal, state and payroll tax every year (2026 law, carried forward with inflation). Income is then before tax and every amount is in dollars, whatever currency says. "off" (the default, any country) takes income as take-home pay.'
                state:
                  type: string
                  example: CA
                  description: Two-letter US state code (DC too) for state income tax. Without it, federal tax only.
                partner_birth:
                  type: integer
                  example: 1988
                  description: A partner's birth year (YYYY). The partner retires at the same time. Every account and income line stays the first person's.
                married:
                  type: boolean
                  default: true
                  description: With a partner, files jointly. false files as two singles.
                dependents:
                  type: array
                  items:
                    type: integer
                  example:
                  - 2015
                  - 2018
                  description: Dependents' birth years (child tax credit until 17, ACA household size).
                pia:
                  type: number
                  example: 2400
                  description: Monthly Social Security benefit at full retirement age, from the SSA statement. The planner computes the benefit for claim_age from it.
                claim_age:
                  type: integer
                  minimum: 62
                  maximum: 70
                  default: 67
                  description: Age Social Security is claimed (62-70), for social_security (with birth) or pia.
                roth_conversion:
                  type: string
                  enum:
                  - none
                  - fill_10
                  - fill_12
                  - fill_22
                  - fill_24
                  - fixed
                  - aca
                  default: none
                  description: Roth conversion ladder from the first retired year, each December from traditional accounts into Roth. fill_12 converts up to the top of the 12% bracket; fixed converts roth_conversion_amount a year; aca stays under the ACA premium credit's income limit. Needs a Roth account (roth, 0 is fine) to convert into; without one nothing converts and the answer says so.
                roth_conversion_amount:
                  type: number
                  example: 30000
                  description: Dollars a year, with roth_conversion=fixed.
                roth_conversion_until:
                  type: integer
                  default: 72
                  description: Age the conversions stop.
            examples:
              minimal:
                summary: Just salary and expenses
                value:
                  salary: 80000
                  expenses: 4000
              typical:
                summary: Assets, income, expenses, and retirement date
                value:
                  birth: 1990
                  retire_age: 55
                  salary: 80000
                  retirement: 200000
                  retirement_contribution: 1500
                  roth: 50000
                  savings: 20000
                  expenses: 4000
              complex:
                summary: Full profile with debt and custom rates
                value:
                  birth: 1990
                  retire_age: 55
                  salary: 80000
                  retirement: 200000
                  retirement_contribution: 1500
                  roth: 50000
                  roth_contribution: 500
                  savings: 20000
                  expenses: 4000
                  debt: 25000
                  debt_rate: 5.5
                  debt_payment: 400
                  debt_name: Student Loan
                  growth: 6
                  inflation: 3
      responses:
        '200':
          description: Their Fire Planner link and the planner's answer.
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - params_applied
                properties:
                  url:
                    type: string
                    description: Full URL to open the Fire Planner with pre-populated data.
                    example: https://firenum.com/fire-planner?birth=1992&retirement=210000&salary=95000&expenses=4000&source=agent
                  params_applied:
                    type: array
                    items:
                      type: string
                    description: List of parameter names that were recognized and applied.
                    example:
                    - birth
                    - retirement
                    - salary
                    - expenses
                  answer:
                    type: object
                    description: 'The planner''s answer, in its words, as their plan shows it once opened (average returns, today''s money, their currency). A field that does not apply is left out. The whole answer is left out once the day''s answers are used up (a limit shared by every caller, reset at 00:00 UTC): the link still opens their plan.'
                    properties:
                      headline:
                        type: string
                        description: When they can retire and how long the money lasts on average returns, or why no date works.
                        example: 'Retiring Jan 2038, at 46: money lasts to age 90'
                      monte_carlo:
                        type: string
                        description: How many of 500 simulated markets the money lasts in.
                        example: money lasts in 129 of 500 simulations
                      backtest:
                        type: string
                        description: How many historical start years since 1872 the money lasts in.
                        example: money lasts in 78 of 98 start years
                      money_left:
                        type: string
                        description: What is left at the end, on average returns, in today's money.
                        example: 'Money left at age 90: $15.6k'
                      spending_room:
                        type: string
                        description: 'With a retirement year of their own: the most they could spend a month and still last.'
                        example: You could spend up to $5,400/mo and the money still lasts to age 90
                      coast:
                        type: string
                        description: Whether they could stop saving today and still retire then (Coast FIRE).
                        example: If you stopped saving today and still retired Jan 2038, the money runs out in 2046. Without more saving the suggested date moves to May 2058, at 66.
                      fire_number:
                        type: number
                        description: 25 times a year's spending (the 4% rule), in their currency.
                        example: 1200000
                      coast_number:
                        type: number
                        description: 'Their Coast FIRE number: what they would need invested today to stop saving and still reach fire_number by coast_age, growing at the plan''s growth less inflation. In their currency.'
                        example: 355752
                      coast_age:
                        type: integer
                        description: 'The retirement age coast_number is for: theirs if they gave one, else 65.'
                        example: 65
                      assumed:
                        type: string
                        description: What the answer assumed that they did not say. Without a salary or side income, an income that covers their spending, contributions and debt payments until they retire.
                        example: 'Income assumed: $5,000/mo until retirement (spending + contributions + debt payments), since none was given. The planner asks for it.'
                      missing:
                        type: array
                        items:
                          type: string
                        description: The parameters the planner needs before it can grade anything (an age, spending). Ask for them and call again.
                        example:
                        - birth
                      assumptions:
                        type: object
                        description: 'What the answer rests on, as the plan''s Assumptions and its lines hold them: rates in % a year, sums in their currency. `models` says how each model that ran works, in the planner''s words; `accounts`, `income`, `spending` and `debts` are their numbers as the planner read them, each with its growth, start and end.'
                        properties:
                          currency:
                            type: string
                            example: USD
                          money:
                            type: string
                            description: 'Sums in today''s money: future amounts are shown at today''s prices.'
                            example: Today's money
                          average_return_pct:
                            type: number
                            description: '% a year before inflation, for accounts on the market rate.'
                            example: 7
                          inflation_pct:
                            type: number
                            description: '% a year.'
                            example: 3
                          retirement:
                            type: string
                            description: 'How the retirement date was chosen: the planner''s suggestion (the earliest month the money lasts) or their own.'
                            example: 'Suggested: the earliest month the money lasts'
                          money_lasts_until:
                            type: string
                            description: The age the money must last to (the year, without a birth year).
                            example: age 90
                          models:
                            type: object
                            description: 'How each model that ran works: Monte Carlo and the backtest are left out when they did not.'
                            properties:
                              average_returns:
                                type: string
                              monte_carlo:
                                type: string
                              backtest:
                                type: string
                          withdrawal_order:
                            type: string
                            description: The order retirement draws on the accounts.
                            example: 'Taxable first: Brokerage, 401(k), Roth IRA'
                          early_withdrawal_penalty:
                            type: string
                            description: Whether retirement accounts wait for the penalty-free age.
                            example: 'Not applied: every account is drawn in order at any age'
                          accounts:
                            type: array
                            description: 'Each counted account: balance, growth and what goes in each month.'
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                balance:
                                  type: number
                                growth_pct:
                                  type: number
                                monthly_contribution:
                                  type: number
                          income:
                            type: array
                            description: 'Each income: its amount, its frequency (monthly, annual, one-time), from (now, retirement or YYYY-MM) and until (retirement, never or YYYY-MM), growth.'
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                amount:
                                  type: number
                                frequency:
                                  type: string
                                  enum:
                                  - monthly
                                  - annual
                                  - one-time
                                from:
                                  type: string
                                until:
                                  type: string
                                growth_pct:
                                  type: number
                          spending:
                            type: array
                            description: Each spending line, as income is, growing with inflation plus its category's offset.
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                amount:
                                  type: number
                                frequency:
                                  type: string
                                  enum:
                                  - monthly
                                  - annual
                                  - one-time
                                from:
                                  type: string
                                until:
                                  type: string
                                growth_pct:
                                  type: number
                          debts:
                            type: array
                            description: 'Each debt: balance, interest and monthly payment.'
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                balance:
                                  type: number
                                interest_pct:
                                  type: number
                                monthly_payment:
                                  type: number
                          taxes:
                            type: string
                            description: 'Off (income is take-home pay), or what US taxes on computes with: the state, filing, dependents and the Roth conversion strategy.'
                          not_modeled:
                            type: string
                            description: What the planner leaves out.
                      table:
                        type: object
                        description: 'Year by year in today''s money, the rows and numbers the planner''s Table shows (3 significant figures): the first and last years, every 5th year and the retirement year. Net worth is at the end of each year: on average returns, and the 10th percentile, median and 90th percentile of the Monte Carlo simulations and of the backtest''s start years, for each model that ran (0 once the money has run out). Income, spending (debt payments not included) and withdrawals are on the average path. `notes` names a part first year and the years that draw on a retirement account while the early withdrawal penalty applies. With taxes=us, `tax` is the year''s federal, state and payroll tax and `tax_rate_pct` its share of the year''s income and withdrawals.'
                        properties:
                          columns:
                            type: array
                            items:
                              type: string
                          rows:
                            type: array
                            items:
                              type: array
                              items:
                                type:
                                - number
                                - 'null'
                          retirement_year:
                            type:
                            - integer
                            - 'null'
                          notes:
                            type: array
                            items:
                              type: string
        '400':
          description: Invalid JSON body or no recognized parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '405':
          description: Method not allowed (use POST).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
      - Fire Plan