API Reference

Lightweight liveness probe. Reports overall app status, methodology and basket versions, and a single database-connectivity check. Intentionally cheap so it can be polled at high frequency — the per-source data-freshness scan lives at /api/v1/status.

Status values: ok or degraded. degraded when the database connectivity ping fails.

curl https://fixedbasket.org/api/v1/health

{
  "status": "ok",
  "methodology_version": "2.2.0",
  "basket_version": "1.0.14",
  "database": "ok"
}

Per-source data-freshness readiness report. Each registered source's latest period is compared against its publish-lag SLA and bucketed GREEN / YELLOW / RED. Heavier than /api/v1/health (one query per source); intended for dashboards and monitoring, not high-frequency probing.

Status values: ok or degraded. degraded when any source is blocking-stale or the freshness check itself errored.

curl https://fixedbasket.org/api/v1/status

{
  "methodology_version": "2.2.0",
  "basket_version": "1.0.14",
  "data": {
    "status": "ok",
    "data_freshness": {
      "summary": { "any_blocking": false, "any_warning": false, "checked": 11 },
      "sources": [ { "source": "eia", "status": "GREEN", "days_old": 6, "cadence": "monthly", "max_lag_days": 60 } ],
      "blocking_sources": []
    }
  }
}

Freshness + version signal for batch consumers — poll this cheaply and refetch data only when latest_month or surface_computed_at changes (or use the ETag / Last-Modified headers on any read for conditional GETs).

Fields: methodology_version, basket_version, latest_month, surface_computed_at, reproducibility, changelog.

curl https://fixedbasket.org/api/v1/versions

National-Average headline numbers — the public-citation surface.

Fields: as_of_month, index_level (Jan 2000 = 100), annual_rate_pct (long-run annualized %/yr — the headline), rolling_12m_rate_pct (trailing-12-month annualized %), rolling_12m_anchor, purchasing_power_usd (what a 2000 dollar buys today = 100 / index_level), long_run_first_month, long_run_last_month, coverage_months.

curl https://fixedbasket.org/api/v1/index/headline

Latest values for all 10 archetypes side-by-side. Returns an array; is_headline: true marks national_average.

curl https://fixedbasket.org/api/v1/index/archetypes

Full monthly time series for one archetype at the national level.

Path parameters. archetype: one of national_average, homeowner, renter, working_parent, retiree, income_lowest_quintile, income_second_quintile, income_middle_quintile, income_fourth_quintile, income_highest_quintile.

Observation shape. {period, index_level, rolling_12m_rate_pct, purchasing_power_usd}.

curl https://fixedbasket.org/api/v1/index/retiree/series

Per-stratum latest price-relative table — machine-readable form of the The Fixed Basket-vs-CPI comparison.

Per row. {stratum, first_period, last_period, latest_relative, coverage_months} anchored at 2000-01 = 1.0.

curl https://fixedbasket.org/api/v1/index/strata

Index of all 52 published geographies, grouped by level (national, states).

Top-level fields. national, states, total_count, published_series_total, level_construction_note.

curl https://fixedbasket.org/api/v1/geographies

National headline for one archetype. Same fields as /index/headline plus archetype and geography: "US".

curl https://fixedbasket.org/api/v1/archetype/working_parent/headline

Full monthly time series for one archetype at the national level.

curl https://fixedbasket.org/api/v1/archetype/renter/series

Per-stratum X-ray decomposition. Top-level annual_rate_pct plus a strata array; each row: {stratum, weight, rate_annualized, contribution_pp, coverage_months}. Contributions sum approximately to the headline annual rate.

curl https://fixedbasket.org/api/v1/archetype/retiree/decomposition

Per-state coverage map. For each stratum: which source band drives the value (state | national), when state-specific data begins, and what share of basket weight is genuinely state-specific.

This endpoint is the §5.8 disclosure surface — readers can see how much of a state headline is genuinely state-resolved versus national-pass-through.

curl https://fixedbasket.org/api/v1/state/CA/coverage

State × archetype headline. Same shape as the archetype headline endpoint with geography set to the state code.

curl https://fixedbasket.org/api/v1/state/CA/archetype/retiree/headline

Full state × archetype monthly time series.

curl https://fixedbasket.org/api/v1/state/TX/archetype/working_parent/series

Per-stratum X-ray for (state, archetype). Same row shape as the archetype decomposition.

curl https://fixedbasket.org/api/v1/state/NY/archetype/renter/decomposition

All geographies for one archetype (or the whole 520-series surface).

Query. archetype (required) — one of the 10 archetypes, or all for every (geography × archetype) cell. include=decomposition (optional) attaches the per-stratum X-ray to each cell. format=csv (optional) returns a CSV of the headline fields.

Each item is the same shape as a per-cell /headline response. Spendable / pinned-as_of vintages are not bulk-served — use the per-cell endpoints for those.

curl "https://fixedbasket.org/api/v1/bulk?archetype=retiree"
curl "https://fixedbasket.org/api/v1/bulk?archetype=all&format=csv"

Flexible time-series query. Two modes depending on whether stratum is supplied.

Required query params. archetype (one of 10 slugs).
Optional. geography (default US), stratum (if present, returns per-stratum price relatives), basket_version, as_of.

curl "https://fixedbasket.org/api/v1/series?archetype=retiree&geography=FL"

curl "https://fixedbasket.org/api/v1/series?archetype=retiree&geography=FL&stratum=healthcare_premium"

Locked basket definition. Per-archetype stratum weights, headline-archetype identifier, canonical stratum list, per-stratum source map.

curl https://fixedbasket.org/api/v1/basket

Methodology version + a short summary of the load-bearing pillars, with links to the canonical documents.

curl https://fixedbasket.org/api/v1/methodology