API Documentation Index: GET /api/v1

For AI agents: this page is also Markdown at /developers/get-api-index.md. Every docs page is listed in /developers/llms.txt.

Returns documentation and list of all available endpoints.

GET /api/v1

Parameters

None.

Example request

curl "https://www.hsatrackr.com/api/v1"

Example response

A real response from the live handler.

{
  "data": {
    "name": "HSA Trackr API",
    "version": "1.0",
    "description": "Free, public API for HSA (Health Savings Account) data including contribution limits, eligible expenses, glossary terms, provider comparisons, calculators, and state tax guides.",
    "rate_limit": "30 requests per minute per IP",
    "endpoints": {
      "limits": {
        "path": "/api/v1/limits",
        "description": "HSA contribution limits, HDHP requirements, and out-of-pocket maximums by year (2004-2026). Omit year to get every year.",
        "params": {
          "year": "optional, e.g. ?year=2026"
        },
        "example": "/api/v1/limits?year=2026"
      },
      "eligible": {
        "path": "/api/v1/eligible",
        "description": "233 HSA-eligible and ineligible medical expenses with categories, costs, and FAQs.",
        "params": {
          "search": "optional text search, e.g. ?search=lasik",
          "category": "optional filter: medical, dental, vision, pharmacy, mental-health, lab-tests, preventive-care, equipment-supplies",
          "eligibility": "optional filter: eligible, partially, ineligible",
          "limit": "optional page size, 1 to 100; omit to get every match",
          "offset": "optional number of results to skip, default 0"
        },
        "example": "/api/v1/eligible?search=lasik&category=vision"
      },
      "eligible/check": {
        "path": "/api/v1/eligible/check",
        "description": "Answer one question: is this item HSA eligible? Best match, match quality, up to 3 alternatives, and the sources behind the ruling.",
        "params": {
          "q": "required item in plain words, 2-120 characters"
        },
        "example": "/api/v1/eligible/check?q=sunscreen"
      },
      "eligible/:slug": {
        "path": "/api/v1/eligible/:slug",
        "description": "Single eligible expense by slug.",
        "example": "/api/v1/eligible/lasik"
      },
      "glossary": {
        "path": "/api/v1/glossary",
        "description": "62 HSA-related terms with definitions, related terms, and FAQs.",
        "params": {
          "search": "optional text search, e.g. ?search=hdhp",
          "category": "optional filter: accounts, plans, contributions, expenses, taxes, strategies, providers"
        },
        "example": "/api/v1/glossary?search=hdhp"
      },
      "glossary/:slug": {
        "path": "/api/v1/glossary/:slug",
        "description": "Single glossary term by slug.",
        "example": "/api/v1/glossary/hsa"
      },
      "providers": {
        "path": "/api/v1/providers",
        "description": "9 HSA providers with fees, investment options, interest rates, and features.",
        "example": "/api/v1/providers"
      },
      "providers/:slug": {
        "path": "/api/v1/providers/:slug",
        "description": "Single HSA provider by slug.",
        "example": "/api/v1/providers/fidelity"
      },
      "providers/compare": {
        "path": "/api/v1/providers/compare",
        "description": "Side-by-side comparison of 2+ HSA providers.",
        "params": {
          "providers": "required, comma-separated slugs, e.g. ?providers=fidelity,lively"
        },
        "example": "/api/v1/providers/compare?providers=fidelity,lively"
      },
      "calculator/tax-savings": {
        "path": "/api/v1/calculator/tax-savings",
        "description": "Calculate HSA tax savings including federal, state, and FICA benefits plus investment growth.",
        "params": {
          "contribution": "annual contribution in dollars (default: 4400)",
          "federalBracket": "federal tax bracket percentage (default: 22)",
          "stateRate": "state income tax rate percentage (default: 5)",
          "years": "years to grow (default: 10)",
          "expectedReturn": "expected annual return percentage (default: 7)"
        },
        "example": "/api/v1/calculator/tax-savings?contribution=4400&federalBracket=22&stateRate=5&years=10"
      },
      "calculator/hsa-vs-cash/:procedure": {
        "path": "/api/v1/calculator/hsa-vs-cash/:procedure",
        "description": "Compare paying for a medical procedure with HSA now vs investing and reimbursing later.",
        "params": {
          "taxRate": "combined tax rate percentage (default: 30)",
          "years": "years to defer reimbursement (default: 10)",
          "returnRate": "expected annual return percentage (default: 7)"
        },
        "example": "/api/v1/calculator/hsa-vs-cash/lasik?taxRate=30&years=10"
      },
      "calculator/form-8889": {
        "path": "/api/v1/calculator/form-8889",
        "description": "Calculate IRS Form 8889 HSA deduction and taxable distributions.",
        "params": {
          "coverage": "\"self\" or \"family\" (default: self)",
          "age55": "catch-up eligible (default: false)",
          "age65": "no penalty on non-qualified distributions (default: false)",
          "directContributions": "your direct contributions (default: 4400)",
          "employerContributions": "W-2 Box 12 Code W amount (default: 0)",
          "totalDistributions": "total distributions from 1099-SA (default: 0)",
          "qualifiedExpenses": "qualified medical expenses (default: 0)",
          "rollovers": "rollover amounts (default: 0)",
          "year": "tax year (default: 2026)"
        },
        "example": "/api/v1/calculator/form-8889?coverage=self&age55=false&directContributions=4400"
      },
      "states/:slug": {
        "path": "/api/v1/states/:slug",
        "description": "51 state HSA tax guides (50 states + DC). Use \"all\" for the full list.",
        "example": "/api/v1/states/california"
      }
    }
  },
  "meta": {
    "source": "https://www.hsatrackr.com",
    "citation_url": "https://www.hsatrackr.com",
    "updated": "2026-01-01",
    "disclaimer": "This information is for educational purposes only and does not constitute tax, legal, or financial advice. Consult a qualified professional for your specific situation.",
    "api_docs": "https://www.hsatrackr.com/api/v1"
  }
}

Response fields

Every response is { data, meta }. meta.citation_url is the public page to cite.

Errors

Full contract: openapi.json. All endpoints: API overview.