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/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

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"
    }
  }
}