openapi: 3.1.0 info: title: firenum.com Agent API version: 1.2.0 description: | Create pre-populated FIRE (Financial Independence, Retire Early) financial planning profiles on firenum.com. POST a JSON object with financial parameters. The API returns a URL that opens the Fire Planner with the data pre-loaded in sandbox mode — the user can review, adjust, and save. All client-side, no account required. Income is annual. Expenses and contributions are monthly. Amounts in whole currency units (not cents). Growth and inflation are percentages. All parameters are optional. Before retirement, any spending, debt payments and contributions that income doesn't cover are paid from savings. If you send expenses, contributions or a debt payment without `salary` or `side_income`, the planner adds an editable monthly "Salary (from calculator)" equal to expenses + contributions + debt payments. It grows with inflation and stops at retirement. servers: - url: https://firenum.com paths: /api/fire-plan: post: operationId: createFirePlan summary: Create a pre-populated FIRE financial planning profile description: | Accepts financial data as a JSON body and returns a URL that opens the Fire Planner with the data pre-loaded in sandbox mode. The user reviews, adjusts, and saves. A banner tells the user the profile was AI-generated. requestBody: required: true content: application/json: schema: type: object properties: # Personal birth: type: integer example: 1990 description: Birth year (YYYY). 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. # Assets (balance in whole currency units, contribution is monthly) 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. # Income (annual amounts) salary: type: number example: 80000 description: Annual gross salary. Grows 3%/year, stops at retirement (open-ended if no retirement date is given). Taxes are not deducted; send a tax amount as an expense if you know it. 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. 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 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 (monthly amounts) 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. # Liabilities 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: FIRE target (portfolio needed). Default 25x annual expenses when expenses are given. # Settings 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. 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: URL to Fire Planner with pre-populated profile. content: application/json: schema: type: object properties: url: type: string description: Full URL to open the Fire Planner with pre-populated data. example: https://firenum.com/fire-planner?salary=80000&expenses=4000&source=agent params_applied: type: array items: type: string description: List of parameter names that were recognized and applied. example: [salary, expenses] "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