openapi: 3.1.0 info: title: firenum.com Agent API version: 1.0.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. 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 salary. side_income: type: number example: 12000 description: Annual side hustle / freelance income. pension: type: number example: 24000 description: Annual pension income. social_security: type: number example: 20000 description: Annual Social Security income. rental_income: type: number example: 18000 description: Annual rental income. # Expenses (monthly amounts) expenses: type: number example: 4000 description: Total monthly expenses (single-bucket shorthand). Use this OR individual categories below. 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". # Settings growth: type: number default: 7 example: 6 description: Default portfolio growth rate (percentage). Overrides individual asset defaults. 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