Skip to main content

​
Portfolio & Strategy Endpoints

These endpoints accept portfolio holdings and return structured factor analytics, stress-test results, optimization proposals, and strategy signals. All outputs include provenance and methodology version metadata.

​
POST /v1/portfolio/analyze

Factor decomposition of a portfolio. Returns exposure to standard risk factors (value, momentum, quality, size, volatility, yield) with attribution breakdown.

​
Request body

{
  "holdings": [
    { "symbol": "AAPL", "weight": 0.25 },
    { "symbol": "JPM", "weight": 0.20 },
    { "symbol": "XOM", "weight": 0.15 },
    { "symbol": "AMZN", "weight": 0.40 }
  ],
  "country": "US",
  "lookback": "1Y"
}
FieldTypeRequiredDescription
holdingsarrayyesArray of { symbol, weight } objects. Weights should sum to 1.0.
holdings[].symbolstringyesTicker symbol.
holdings[].weightnumberyesPortfolio weight as a decimal (0.0 to 1.0).
countrystringnoISO 3166-1 alpha-2 country code. Defaults to US.
lookbackstringnoLookback window. One of 3M, 6M, 1Y, 3Y, 5Y. Defaults to 1Y.

​
Example

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"symbol":"AAPL","weight":0.5},{"symbol":"JPM","weight":0.5}],"lookback":"1Y"}' \
  "https://api.secapi.ai/v1/portfolio/analyze"

​
POST /v1/portfolio/stress-test

Stress-test a portfolio against historical scenarios. Returns projected drawdown, recovery timeline, and per-holding impact.

​
Request body

{
  "holdings": [
    { "symbol": "AAPL", "weight": 0.50 },
    { "symbol": "TLT", "weight": 0.50 }
  ],
  "category": "rate_shock"
}
FieldTypeRequiredDescription
holdingsarrayyesArray of { symbol, weight } objects.
categorystringnoScenario category filter. One of rate_shock, credit_event, equity_crash, geopolitical, pandemic. Omit for all scenarios.

​
Example

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"symbol":"AAPL","weight":0.5},{"symbol":"TLT","weight":0.5}],"category":"equity_crash"}' \
  "https://api.secapi.ai/v1/portfolio/stress-test"

​
POST /v1/portfolio/optimize

Portfolio optimization across three objectives. Returns proposed weight adjustments, expected factor exposures, and constraint satisfaction metadata.

​
Request body

{
  "holdings": [
    { "symbol": "AAPL", "weight": 0.30 },
    { "symbol": "JPM", "weight": 0.30 },
    { "symbol": "XOM", "weight": 0.20 },
    { "symbol": "AMZN", "weight": 0.20 }
  ],
  "objective": "min_drawdown",
  "country": "US",
  "lookback": "3Y"
}
FieldTypeRequiredDescription
holdingsarrayyesArray of { symbol, weight } objects.
objectivestringyesOptimization objective. One of factor_neutral, min_drawdown, regime_aware.
countrystringnoISO 3166-1 alpha-2 country code. Defaults to US.
lookbackstringnoLookback window. One of 1Y, 3Y, 5Y. Defaults to 3Y.

​
Objectives

  • factor_neutral — minimize net factor tilts across the portfolio
  • min_drawdown — minimize expected maximum drawdown under historical stress scenarios
  • regime_aware — tilt weights based on the current macro regime classification

​
Example

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"symbol":"AAPL","weight":0.5},{"symbol":"JPM","weight":0.5}],"objective":"factor_neutral"}' \
  "https://api.secapi.ai/v1/portfolio/optimize"

​
GET /v1/model-portfolios/:id/factor-view

Factor analysis for a named model portfolio. Returns the same factor decomposition structure as /v1/portfolio/analyze without requiring holdings in the request.
ParameterInTypeRequiredDescription
idpathstringyesModel portfolio identifier.

​
Example

curl -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  "https://api.secapi.ai/v1/model-portfolios/us-quality-dividend/factor-view"

​
POST /v1/strategies/factor-rotation

Generate factor rotation signals based on macro regime, momentum, and valuation inputs. Returns ranked factor tilts with conviction scores.

​
Request body

{
  "country": "US",
  "lookback": "6M"
}
FieldTypeRequiredDescription
countrystringnoISO 3166-1 alpha-2 country code. Defaults to US.
lookbackstringnoLookback window for signal generation. One of 3M, 6M, 1Y. Defaults to 6M.

​
Example

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","lookback":"6M"}' \
  "https://api.secapi.ai/v1/strategies/factor-rotation"

​
POST /v1/strategies/regime-screen

Screen securities through a regime-aware factor lens. Returns securities ranked by fit to the current macro regime with factor exposure detail.

​
Request body

{
  "country": "US",
  "lookback": "1Y"
}
FieldTypeRequiredDescription
countrystringnoISO 3166-1 alpha-2 country code. Defaults to US.
lookbackstringnoLookback window. One of 6M, 1Y, 3Y. Defaults to 1Y.

​
Example

curl -X POST \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","lookback":"1Y"}' \
  "https://api.secapi.ai/v1/strategies/regime-screen"