Portfolio & Strategy Endpoints

These endpoints accept portfolio holdings and return structured factor analytics, stress-test results, optimizer scenarios, and strategy research outputs. 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"
}

Field	Type	Required	Description
`holdings`	array	yes	Array of `{ symbol, weight }` objects. Weights should sum to 1.0.
`holdings[].symbol`	string	yes	Ticker symbol.
`holdings[].weight`	number	yes	Portfolio weight as a decimal (0.0 to 1.0).
`country`	string	no	ISO 3166-1 alpha-2 country code. Defaults to `US`.
`lookback`	string	no	Lookback window. One of `3M`, `6M`, `1Y`, `3Y`, `5Y`. Defaults to `1Y`.

Example

curl -X POST \
  -H "x-api-key: $SECAPI_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"
}

Field	Type	Required	Description
`holdings`	array	yes	Array of `{ symbol, weight }` objects.
`category`	string	no	Scenario category filter. One of `rate_shock`, `credit_event`, `equity_crash`, `geopolitical`, `pandemic`. Omit for all scenarios.

Example

curl -X POST \
  -H "x-api-key: $SECAPI_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 bounded candidate scenarios, return/risk proxies, constraint satisfaction metadata, and non-advice disclosures.

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",
  "constraints": {
    "maxCandidates": 3,
    "turnoverLimit": 0.20,
    "maxRuntimeMs": 750
  }
}

Field	Type	Required	Description
`holdings`	array	yes	Array of `{ symbol, weight }` objects.
`objective`	string	yes	Optimization objective. One of `factor_neutral`, `min_drawdown`, `regime_aware`.
`country`	string	no	ISO 3166-1 alpha-2 country code. Defaults to `US`.
`lookback`	string	no	Lookback window. One of `1Y`, `3Y`, `5Y`. Defaults to `3Y`.
`constraints`	object	no	Runtime and portfolio controls such as `maxCandidates`, `maxPositionWeight`, `turnoverLimit`, and `maxRuntimeMs`.

Objectives

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

Optimizer outputs are analytical model scenarios for research and engineering workflows, not personalized investment advice or a recommendation to trade.

Example

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

POST /v1/strategies/factor-rotation

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

Request body

{
  "country": "US",
  "lookback": "6M"
}

Field	Type	Required	Description
`country`	string	no	ISO 3166-1 alpha-2 country code. Defaults to `US`.
`lookback`	string	no	Lookback window for signal generation. One of `3M`, `6M`, `1Y`. Defaults to `6M`.

Example

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

Plans & pricing

Products

Workflow guides

Concepts & trust

Tutorials

Migrate to SEC API

Solutions

Compare

API guides by topic

Portfolio & Strategy Endpoints

POST /v1/portfolio/analyze

Request body

Example

POST /v1/portfolio/stress-test

Request body

Example

POST /v1/portfolio/optimize

Request body

Objectives

Example

POST /v1/strategies/factor-rotation

Request body

Example

​POST /v1/portfolio/analyze

​Request body

​Example

​POST /v1/portfolio/stress-test

​Request body

​Example

​POST /v1/portfolio/optimize

​Request body

​Objectives

​Example

​POST /v1/strategies/factor-rotation

​Request body

​Example

POST /v1/portfolio/analyze

Request body

Example

POST /v1/portfolio/stress-test

Request body

Example

POST /v1/portfolio/optimize

Request body

Objectives

Example

POST /v1/strategies/factor-rotation

Request body

Example