{
  "openapi": "3.1.0",
  "info": {
    "title": "TrueAdvisor FIRE Calculator API",
    "description": "Backtest a retirement plan against 154 years of real U.S. market history (1871–2024). Uses S&P 500 total returns, government bond yields, and CPI inflation from the Shiller dataset at Yale University. Supports two modes: simulate (backtest a specific plan) and find_spending (find the maximum safe spending for a target success rate).",
    "version": "1.0.0",
    "contact": {
      "name": "TrueAdvisor",
      "url": "https://trueadvisor.com"
    }
  },
  "servers": [
    {
      "url": "https://trueadvisor.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/fire-calculator/": {
      "get": {
        "operationId": "fireCalculator",
        "summary": "Backtest a retirement plan or find safe spending",
        "description": "Runs a retirement plan through every historical market period from 1871–2024 and returns the success rate, ending balance statistics, and worst/best case scenarios. Use mode=find_spending to find the maximum safe annual spending for a target success rate.",
        "parameters": [
          {
            "name": "portfolio",
            "in": "query",
            "required": true,
            "description": "Starting portfolio value in dollars",
            "schema": {
              "type": "number",
              "example": 1000000
            }
          },
          {
            "name": "annual_spending",
            "in": "query",
            "required": false,
            "description": "Annual spending in dollars. Required when mode=simulate.",
            "schema": {
              "type": "number",
              "example": 40000
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "simulate: backtest a specific plan. find_spending: find the maximum safe spending for a target success rate.",
            "schema": {
              "type": "string",
              "enum": ["simulate", "find_spending"],
              "default": "simulate"
            }
          },
          {
            "name": "retirement_years",
            "in": "query",
            "required": false,
            "description": "Length of retirement in years (1–80)",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 80
            }
          },
          {
            "name": "equity_pct",
            "in": "query",
            "required": false,
            "description": "Stock allocation percentage (0–100). The remainder goes to bonds.",
            "schema": {
              "type": "number",
              "default": 75,
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "expense_ratio",
            "in": "query",
            "required": false,
            "description": "Annual fund expense ratio as a percentage (e.g., 0.1 means 0.1%)",
            "schema": {
              "type": "number",
              "default": 0.1,
              "minimum": 0,
              "maximum": 5
            }
          },
          {
            "name": "spending_model",
            "in": "query",
            "required": false,
            "description": "constant: spending is adjusted for inflation each year. percentage: spending is a fixed percentage of current portfolio value.",
            "schema": {
              "type": "string",
              "enum": ["constant", "percentage"],
              "default": "constant"
            }
          },
          {
            "name": "ss_amount",
            "in": "query",
            "required": false,
            "description": "Annual Social Security income in dollars, automatically adjusted for inflation",
            "schema": {
              "type": "number",
              "default": 0
            }
          },
          {
            "name": "ss_start_year",
            "in": "query",
            "required": false,
            "description": "Year of retirement when Social Security begins (0-indexed, so 0 means year 1)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "pension_amount",
            "in": "query",
            "required": false,
            "description": "Annual pension income in dollars",
            "schema": {
              "type": "number",
              "default": 0
            }
          },
          {
            "name": "pension_start_year",
            "in": "query",
            "required": false,
            "description": "Year of retirement when pension begins (0-indexed)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "pension_inflation_adj",
            "in": "query",
            "required": false,
            "description": "Whether pension adjusts for inflation",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "target_success_rate",
            "in": "query",
            "required": false,
            "description": "For find_spending mode: desired historical success rate percentage (1–100)",
            "schema": {
              "type": "number",
              "default": 95,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Simulation or safe spending results",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "title": "SimulateResponse",
                      "properties": {
                        "mode": { "type": "string", "const": "simulate" },
                        "inputs": {
                          "type": "object",
                          "properties": {
                            "portfolio": { "type": "number" },
                            "annual_spending": { "type": "number" },
                            "retirement_years": { "type": "integer" },
                            "equity_pct": { "type": "number" },
                            "expense_ratio": { "type": "number" },
                            "spending_model": { "type": "string" },
                            "withdrawal_rate_pct": { "type": "number" }
                          }
                        },
                        "results": {
                          "type": "object",
                          "properties": {
                            "success_rate": { "type": "number", "description": "Percentage of historical periods that survived" },
                            "total_cycles": { "type": "integer" },
                            "success_count": { "type": "integer" },
                            "median_ending_balance": { "type": "number" },
                            "average_ending_balance": { "type": "number" },
                            "lowest_ending_balance": { "type": "number" },
                            "highest_ending_balance": { "type": "number" },
                            "worst_start_year": { "type": "integer" },
                            "best_start_year": { "type": "integer" }
                          }
                        },
                        "summary": { "type": "string" },
                        "methodology": { "type": "string" },
                        "data_range": { "type": "string" },
                        "source": { "type": "string", "format": "uri" }
                      }
                    },
                    {
                      "type": "object",
                      "title": "FindSpendingResponse",
                      "properties": {
                        "mode": { "type": "string", "const": "find_spending" },
                        "inputs": {
                          "type": "object",
                          "properties": {
                            "portfolio": { "type": "number" },
                            "retirement_years": { "type": "integer" },
                            "equity_pct": { "type": "number" },
                            "expense_ratio": { "type": "number" },
                            "target_success_rate": { "type": "number" }
                          }
                        },
                        "results": {
                          "type": "object",
                          "properties": {
                            "safe_annual_spending": { "type": "number" },
                            "safe_withdrawal_rate_pct": { "type": "number" },
                            "target_success_rate": { "type": "number" }
                          }
                        },
                        "summary": { "type": "string" },
                        "methodology": { "type": "string" },
                        "data_range": { "type": "string" },
                        "source": { "type": "string", "format": "uri" }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}