{"openapi":"3.1.0","info":{"title":"re-invest public API","version":"1.0.0","description":"Read-only access to metro forecasts, signals, and FHFA HPI history. All endpoints require a Bearer token issued from /app/api-keys (Enterprise tier).","contact":{"name":"re-invest support","url":"https://re-invest.ai/about#contact"},"license":{"name":"Proprietary","url":"https://re-invest.ai/legal/terms"}},"servers":[{"url":"https://re-invest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"API key issued from /app/api-keys. Sent as `Authorization: Bearer <token>`."}},"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"}}}}},"paths":{"/markets":{"get":{"summary":"List markets","description":"Every CBSA we score, with its latest signal, risk grade, and 12-month forecast.","tags":["markets"],"responses":{"200":{"description":"Market list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/markets/{cbsa}":{"get":{"summary":"Get a single market","tags":["markets"],"parameters":[{"name":"cbsa","in":"path","required":true,"description":"5-digit Census Core-Based Statistical Area code","schema":{"type":"string","pattern":"^\\d{5}$","example":"12060"}}],"responses":{"200":{"description":"Market detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"No such CBSA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets/{cbsa}/history":{"get":{"summary":"FHFA HPI history for a market","description":"Full quarterly series for the requested CBSA.","tags":["markets"],"parameters":[{"name":"cbsa","in":"path","required":true,"description":"5-digit Census Core-Based Statistical Area code","schema":{"type":"string","pattern":"^\\d{5}$","example":"12060"}}],"responses":{"200":{"description":"Quarterly HPI observations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HpiObservation"}}}}}}}}}},"/forecasts":{"get":{"summary":"All-market 12-month forecasts","description":"Identical shape to /markets but restricted to metros with a scored forecast.","tags":["forecasts"],"responses":{"200":{"description":"Current forecasts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}}}}}}}}},"/forecasts/{cbsa}/history":{"get":{"summary":"Historical forecasts for a market","description":"What the model predicted at each past run — useful for walk-forward analysis.","tags":["forecasts"],"parameters":[{"name":"cbsa","in":"path","required":true,"description":"5-digit Census Core-Based Statistical Area code","schema":{"type":"string","pattern":"^\\d{5}$","example":"12060"}}],"responses":{"200":{"description":"Forecast history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ForecastHistory"}}}}}}}}}},"/forecast-runs":{"get":{"summary":"List model runs","description":"Version, timestamp, and feature set for every completed model run.","tags":["forecasts"],"responses":{"200":{"description":"Forecast runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ForecastRun"}}}}}}}}}},"/observations":{"get":{"summary":"Raw observations (macro or HPI)","tags":["data"],"parameters":[{"name":"series_id","in":"query","required":true,"description":"FRED id (e.g., FEDFUNDS) or metro_hpi","schema":{"type":"string","example":"FEDFUNDS"}},{"name":"since","in":"query","required":false,"description":"ISO date lower bound","schema":{"type":"string","example":"2015-01-01"}}],"responses":{"200":{"description":"Observation list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MacroObservation"}}}}}}}}}}}}