API Reference

Developer Quickstarts

Copy-paste examples to call the API directly. Replace YOUR_API_KEY with a key from your dashboard.

curl -X POST https://api.retirelab.dev/api/v1/plan/demo \
  -H "Content-Type: application/json" \
  -d '{
    "current_age": 35,
    "target_retirement_age": 55,
    "current_assets": 400000,
    "annual_contribution": 24000,
    "annual_withdrawal": 60000,
    "risk_tolerance": "MEDIUM"
  }'

curl -X POST https://api.retirelab.dev/api/v1/plan/fire-scenarios \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_age": 35,
    "target_retirement_age": 65,
    "current_assets": 400000,
    "annual_contribution": 24000,
    "annual_withdrawal": 60000,
    "risk_tolerance": "MEDIUM"
  }'

import requests

result = requests.post(
    "https://api.retirelab.dev/api/v1/plan/fire-scenarios",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "current_age": 35,
        "target_retirement_age": 65,
        "current_assets": 400_000,
        "annual_contribution": 24_000,
        "annual_withdrawal": 60_000,
        "risk_tolerance": "MEDIUM",
    },
).json()

print(f"Success probability: {result['base']['success_probability']:.0%}")
print(f"FI Number: ${result['fi_number']:,.0f}")

const res = await fetch("https://api.retirelab.dev/api/v1/plan/fire-scenarios", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    current_age: 35,
    target_retirement_age: 65,
    current_assets: 400000,
    annual_contribution: 24000,
    annual_withdrawal: 60000,
    risk_tolerance: "MEDIUM",
  }),
});

const data = await res.json();
console.log(`Success: ${Math.round(data.base.success_probability * 100)}%`);
console.log(`FI Number: $${data.fi_number.toLocaleString()}`);

{
  "lean": {
    "annual_withdrawal": 48000,
    "success_probability": 0.94,
    "retirement_assets_p50": 1520000,
    "planning_assets_p50": 440000
  },
  "base": {
    "annual_withdrawal": 60000,
    "success_probability": 0.82,
    "retirement_assets_p50": 1520000,
    "planning_assets_p50": 218000
  },
  "fat": {
    "annual_withdrawal": 72000,
    "success_probability": 0.67,
    "retirement_assets_p50": 1520000,
    "planning_assets_p50": -105000
  },
  "fi_number": 1500000,
  "disclaimer": "This analysis is for educational purposes only..."
}

Traditional retirement with Social Security & pension

Same fields as above, plus optional Social Security, pension, and pre-Medicare healthcare offsets. Net withdrawal is automatically adjusted.

result = requests.post(
    "https://api.retirelab.dev/api/v1/plan/traditional",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "current_age": 55,
        "target_retirement_age": 65,
        "current_assets": 800_000,
        "annual_contribution": 30_000,
        "annual_withdrawal": 80_000,
        "risk_tolerance": "MEDIUM",
        "ss_monthly": 2_200,      # expected Social Security benefit
        "ss_age": 67,             # age to claim (62–70)
        "pension_monthly": 500,   # optional pension income
        "healthcare_annual": 8_000,  # pre-Medicare bridge cost
    },
).json()

# response also includes an "adjustments" object showing the offset math
print(result["adjustments"]["net_annual_withdrawal_used"])

Sharing Results

Any simulation run on the RetireLab dashboard can be saved as a permanent public link and shared with anyone — no account required to view. Links work for FIRE, Traditional, and Coast FIRE plans.

From the dashboard

1. Run any simulation in the dashboard.
2. Click Share results below the results table.
3. A permanent link is generated and copied to your clipboard automatically.
4. Share the link anywhere — Reddit, Twitter/X, Discord, or with a financial advisor.

Shared result URL format

https://retirelab.dev/results/550e8400-e29b-41d4-a716-446655440000

Create a shareable link via API

No API key required for POST or GET. Auth is optional — if you include a Bearer token the result is linked to your account.

# Create a shareable link
curl -X POST https://api.retirelab.dev/api/v1/shared-results/ \
  -H "Content-Type: application/json" \
  -d '{
    "plan_type": "fire",
    "title": "FIRE plan — retire at 55",
    "inputs": {
      "current_age": 35,
      "target_retirement_age": 55,
      "current_assets": 400000,
      "annual_withdrawal": 60000,
      "risk_tolerance": "MEDIUM"
    },
    "results": {
      "fi_number": 1500000,
      "base": { "success_probability": 0.82, "annual_withdrawal": 60000,
                "retirement_assets_p50": 1520000, "planning_assets_p50": 218000 }
    }
  }'

# Response
{ "id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-03-06T12:00:00" }

# Retrieve a shared result (public — no auth)
curl https://api.retirelab.dev/api/v1/shared-results/550e8400-e29b-41d4-a716-446655440000

# Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "plan_type": "fire",
  "title": "FIRE plan — retire at 55",
  "inputs": { ... },
  "results": { ... },
  "created_at": "2026-03-06T12:00:00"
}

Embeddable Widget

Embed the RetireLab FIRE calculator on any website with a single <iframe>. No API key required — the embed uses the public demo endpoint (10 runs/hour per IP).

<iframe
  src="https://retirelab.dev/embed"
  width="380"
  height="420"
  frameborder="0"
  style="border-radius:12px;border:1px solid #e4e4e7"
></iframe>

Preview the widget at retirelab.dev/embed.

Errors

Rate limits

Simulations are counted across your API keys and dashboard usage combined, and reset on the first day of each month.

See pricing for full tier comparison.

Support

Found a bug, hit an undocumented edge case, or need help integrating? Email us — we read every message and reply within one business day. Pro and Creator tier customers get priority response.

Key endpoints

Common endpoints are listed below.