# HSA Trackr API

> For AI agents: this page is also Markdown at [/developers.md](https://www.hsatrackr.com/developers.md). Every docs page is listed in [/developers/llms.txt](https://www.hsatrackr.com/developers/llms.txt).

A free, read-only JSON API for HSA eligibility rulings, IRS contribution limits, provider fees, state tax rules and HSA calculators. No API key.

Ask whether an expense is HSA eligible, get this year's contribution limits, compare HSA providers, or run the same calculators the site uses. Every answer links back to the public page that explains it.

## Quickstart

Check one item. No key, no sign-up:

```bash
curl "https://www.hsatrackr.com/api/v1/eligible/check?q=ozempic"
```

```json
{
  "data": {
    "query": "ozempic",
    "found": true,
    "matchQuality": "exact",
    "match": {
      "slug": "ozempic",
      "name": "GLP-1 Prescription Medications",
      "category": "pharmacy",
      "eligibility": "eligible",
      "description": "Prescribed GLP-1 medicines such as Ozempic, Wegovy, Mounjaro, and Zepbound are HSA-eligible prescription drug expenses.",
      "requirements": "Keep the valid prescription and itemized pharmacy receipt, and subtract any insurance or other reimbursement. For a compounded product, confirm that it was prescribed for you and dispensed by a state-licensed pharmacy. HSA eligibility does not establish FDA approval, product quality, or legality.",
      "sourceBasis": [
        {
          "label": "IRS Publication 502: Medicines",
          "url": "https://www.irs.gov/publications/p502",
          "supports": "Amounts paid for medicines and drugs prescribed for an individual are includible medical expenses.",
          "reviewedDate": "2026-07-14"
        },
        {
          "label": "IRS Publication 969: Qualified medical expenses",
          "url": "https://www.irs.gov/publications/p969",
          "supports": "HSA distributions are tax-free only for uncompensated qualified medical expenses incurred after the HSA was established.",
          "reviewedDate": "2026-07-14"
        }
      ],
      "url": "https://www.hsatrackr.com/eligible/ozempic"
    },
    "alternatives": [],
    "searchUrl": "https://www.hsatrackr.com/eligible?search=ozempic"
  },
  "meta": {
    "source": "https://www.hsatrackr.com/eligible/ozempic",
    "citation_url": "https://www.hsatrackr.com/eligible/ozempic",
    "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"
  }
}
```

`found` is true only for an `exact` or `strong` match. When it is false, `match` is null and `alternatives` holds weak suggestions you can offer as "did you mean". You can pass the question as typed: `q=is ozempic hsa eligible` gives the same answer.

## The basics

- Base URL: `https://www.hsatrackr.com/api/v1`
- Auth: none. Every endpoint is a public GET.
- CORS: open (`Access-Control-Allow-Origin: *`), so browser extensions and front ends can call it directly.
- Rate limit: 30 requests per minute per IP. Over the limit you get `429` with `Retry-After`.
- Shape: every success is `{ data, meta }`. A 400 or 404 is `{ error, meta }`; a 429 is `{ error }`.
- Citations: `meta.citation_url` is the public page behind the answer. Link it when you show the answer to people.
- `/api/v1/eligible` takes `limit` (1 to 100) and `offset`. Without `limit` it returns every match. The other lists are small and always return everything.

## Endpoints

| Endpoint | What it answers |
| --- | --- |
| [GET /api/v1](https://www.hsatrackr.com/developers/get-api-index) | API Documentation Index |
| [GET /api/v1/limits](https://www.hsatrackr.com/developers/get-contribution-limits) | HSA Contribution Limits |
| [GET /api/v1/eligible](https://www.hsatrackr.com/developers/list-eligible-expenses) | Search HSA-Eligible Expenses |
| [GET /api/v1/eligible/check](https://www.hsatrackr.com/developers/check-eligibility) | Check One Item |
| [GET /api/v1/eligible/{slug}](https://www.hsatrackr.com/developers/get-eligible-expense) | Get Single Expense Detail |
| [GET /api/v1/glossary](https://www.hsatrackr.com/developers/list-glossary-terms) | Search Glossary Terms |
| [GET /api/v1/glossary/{slug}](https://www.hsatrackr.com/developers/get-glossary-term) | Get Single Glossary Term |
| [GET /api/v1/providers](https://www.hsatrackr.com/developers/list-providers) | List HSA Providers |
| [GET /api/v1/providers/{slug}](https://www.hsatrackr.com/developers/get-provider) | Get Single Provider Detail |
| [GET /api/v1/providers/compare](https://www.hsatrackr.com/developers/compare-providers) | Compare Providers |
| [GET /api/v1/states/{slug}](https://www.hsatrackr.com/developers/get-state-guide) | Get State HSA Tax Guide |
| [GET /api/v1/calculator/tax-savings](https://www.hsatrackr.com/developers/calculate-tax-savings) | Tax Savings Calculator |
| [GET /api/v1/calculator/hsa-vs-cash/{procedure}](https://www.hsatrackr.com/developers/calculate-hsa-vs-cash) | HSA vs Cash Cost Comparison |
| [GET /api/v1/calculator/form-8889](https://www.hsatrackr.com/developers/calculate-form8889) | Form 8889 Deduction Calculator |

## Guides

- [Eligibility data: what the rulings mean and where they come from](https://www.hsatrackr.com/developers/eligibility-data)
- [Errors and rate limits](https://www.hsatrackr.com/developers/errors-and-rate-limits)

## Machine-readable

- [OpenAPI 3 spec](https://www.hsatrackr.com/openapi.json) (also at `/.well-known/openapi.json`)
- [llms.txt for these docs](https://www.hsatrackr.com/developers/llms.txt)
- Every docs page has a Markdown twin: add `.md` to the URL, or send `Accept: text/markdown`.

> Not tax advice. Rulings summarize IRS Publication 502 and related guidance. Plan rules and your own situation can change the answer.