API reference

/api/v1

Read-only access to metro forecasts, signals, and FHFA HPI history. All endpoints require a Bearer token issued from /app/api-keys (Enterprise tier). Version 1.0.0 · OpenAPI 3.1.0.

openapi.json Generate a key Try it live

Authentication

Every request must carry a Bearer token issued from /app/api-keys. Keys are tied to an Enterprise subscription. Rate limit: 600 req/min by default; request an increase from your account manager.

curl https://re-invest.ai/api/v1/forecasts \
  -H "Authorization: Bearer $RI_API_KEY" \
  -H "Accept: application/json"

Endpoints

GET/marketsmarkets

List markets

Every CBSA we score, with its latest signal, risk grade, and 12-month forecast.

Responses

200Market list
401Missing or invalid API key
429Rate limited

GET/markets/{cbsa}markets

Get a single market

Parameters

Name	In	Type	Description
cbsa*	path	string · e.g. 12060	5-digit Census Core-Based Statistical Area code

Responses

200Market detail
404No such CBSA

GET/markets/{cbsa}/historymarkets

FHFA HPI history for a market

Full quarterly series for the requested CBSA.

Parameters

Name	In	Type	Description
cbsa*	path	string · e.g. 12060	5-digit Census Core-Based Statistical Area code

Responses

200Quarterly HPI observations

GET/markets/{cbsa}/forecast-trackmarkets

Track of our forecasts for a market across runs

One row per past forecast run that scored this metro. Useful for showing how the model's view of a market has evolved month-over-month — pairs with the per-market /performance backtest.

Parameters

Name	In	Type	Description
cbsa*	path	string · e.g. 12060	5-digit Census Core-Based Statistical Area code

Responses

200Forecast track (one row per run)

GET/moversforecasts

Top metros that moved most this run

Largest |Δ| in the 12-month forecast between the current and prior run. Useful for 'biggest revisions this month' surfaces. Default top 5 — pass `limit` (max 50).

Parameters

Name	In	Type	Description
limit	query	integer · e.g. 5	Number of metros to return (default 5, max 50).

Responses

200Movers (sorted by |delta_pp| desc)

GET/forecast-backtestforecasts

Latest aggregate backtest of the baseline forecast

One row — the most recent rolling-realized backtest. Returns null when the model hasn't been running long enough (needs ≥12 months of forecast history). Pairs with the public /performance page.

Responses

200Backtest snapshot or null

GET/forecastsforecasts

All-market 12-month forecasts

Identical shape to /markets but restricted to metros with a scored forecast.

Responses

200Current forecasts

GET/forecasts/{cbsa}/historyforecasts

Historical forecasts for a market

What the model predicted at each past run — useful for walk-forward analysis.

Parameters

Name	In	Type	Description
cbsa*	path	string · e.g. 12060	5-digit Census Core-Based Statistical Area code

Responses

200Forecast history

GET/forecast-runsforecasts

List model runs

Version, timestamp, and feature set for every completed model run.

Responses

200Forecast runs

GET/observationsdata

Raw observations (macro or HPI)

Parameters

Name	In	Type	Description
series_id*	query	string · e.g. FEDFUNDS	FRED id (e.g., FEDFUNDS) or metro_hpi
since	query	string · e.g. 2015-01-01	ISO date lower bound

Responses

200Observation list

GET/seriesdata

List available series

Every macro + metric series we publish, with its cadence and source.

Responses

200Series catalog

GET/signalsforecasts

Latest market signals

Per-CBSA expand / hold / contract signal + risk grade for the most recent scored run.

Responses

200Market signals

GET/statusdata

Platform health snapshot

No auth required. Returns overall status plus per-component (api / pipeline / model) and per-source freshness state. Cached 60s at the edge.

Responses

200Status document

GET/healthdata

Readiness ping

Lightweight 200 whenever the Next.js layer is reachable. For platform-wide health use `/status`.

Responses

200OK

Schemas

Market

{
  "type": "object",
  "required": [
    "cbsa",
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer"
    },
    "cbsa": {
      "type": "string",
      "pattern": "^\\d{5}$",
      "example": "12060"
    },
    "name": {
      "type": "string",
      "example": "Atlanta-Sandy Springs-Alpharetta, GA"
    },
    "signal": {
      "type": "string",
      "enum": [
        "expand",
        "hold",
        "contract"
      ],
      "nullable": true
    },
    "risk_score": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D",
        "F"
      ],
      "nullable": true
    },
    "yoy_price": {
      "type": "number",
      "nullable": true,
      "description": "Trailing-12-month HPI change (percent)"
    },
    "forecast_12m": {
      "type": "number",
      "nullable": true,
      "description": "Model 12-month forecast return (percent)"
    }
  }
}

HpiObservation

{
  "type": "object",
  "required": [
    "period_start",
    "value"
  ],
  "properties": {
    "period_start": {
      "type": "string",
      "format": "date",
      "example": "2024-10-01"
    },
    "value": {
      "type": "number",
      "description": "Indexed HPI level"
    }
  }
}

ForecastHistory

{
  "type": "object",
  "required": [
    "run_at",
    "model_version",
    "target_period",
    "point"
  ],
  "properties": {
    "run_at": {
      "type": "string",
      "format": "date-time"
    },
    "model_version": {
      "type": "string",
      "example": "xgb-baseline-v2"
    },
    "horizon_months": {
      "type": "integer",
      "example": 12
    },
    "target_period": {
      "type": "string",
      "format": "date",
      "example": "2026-10-01"
    },
    "point": {
      "type": "number"
    },
    "lower_80": {
      "type": "number",
      "nullable": true
    },
    "upper_80": {
      "type": "number",
      "nullable": true
    }
  }
}

ForecastRun

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "model_version": {
      "type": "string"
    },
    "run_at": {
      "type": "string",
      "format": "date-time"
    },
    "features": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "nullable": true
    },
    "notes": {
      "type": "string",
      "nullable": true
    }
  }
}

MacroObservation

{
  "type": "object",
  "required": [
    "period_start",
    "value"
  ],
  "properties": {
    "period_start": {
      "type": "string",
      "format": "date"
    },
    "value": {
      "type": "number"
    }
  }
}

Error

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    }
  }
}