Stress test scenarios

Use these endpoints to manage scenario-based stress testing definitions. These scenarios can then be run through POST /portfolios with stress_test_enabled: true.

This API is the mechanism for sector, sub-sector, underlying, and expiry-specific stress testing. It is separate from stress_sensitivities, which defines a uniform sensitivity grid rather than reusable stress scenarios.

Scenario-based stress testing uses hierarchical matching. For each position, the most specific matching rule wins: expiry > underlying > sub_sector > sector.

GET/stress-test/scenarios

List scenarios

Returns the scenarios available to the caller.

This response may include both:

client-defined scenarios created by the caller
built-in scenarios provided by Cumulus9

cURL

curl -sSX GET "$C9_API_ENDPOINT/stress-test/scenarios" \
  -H "Authorization: Bearer $C9_API_SECRET"

[
  {
    "scenario_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scenario_name": "Broad risk-off (sector)"
  }
]

POST/stress-test/scenarios

Create scenarios

Uploads one or more client-defined scenarios.

Each scenario includes:

scenario_name
scenario_definition

The scenario_definition can declare shocks at four levels:

sector
sub_sector
underlying
expiry

Example request:

[
  {
    "scenario_name": "Broad risk-off (sector)",
    "scenario_definition": {
      "sector": {
        "Equity": { "underlying": -0.10, "volatility": 0.20 },
        "Energy": { "underlying": -0.05, "volatility": 0.10 }
      }
    }
  },
  {
    "scenario_name": "Equity index crash (sub_sector)",
    "scenario_definition": {
      "sector": {
        "Equity": { "underlying": -0.05, "volatility": 0.10 }
      },
      "sub_sector": {
        "Index": {
          "override": true,
          "underlying": -0.20,
          "volatility": 0.40
        }
      }
    }
  }
]

Example response:

{
  "scenario_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  ]
}

For a complete walkthrough that uploads scenarios and runs them on a portfolio:

Read the Stress testing guide

DELETE/stress-test/scenarios

Delete scenarios

Deletes a client-defined scenario by scenario_id.

The public Python example uses this to remove prior client-defined scenarios before uploading a fresh set.

cURL

curl -sSX DELETE "$C9_API_ENDPOINT/stress-test/scenarios?scenario_id=$SCENARIO_ID" \
  -H "Authorization: Bearer $C9_API_SECRET"

DELETE only affects scenarios owned by the caller. Built-in scenarios are not removed.

To execute uploaded scenarios, submit a portfolio with:

{
  "stress_test_enabled": true,
  "stress_test_details_enabled": true
}

through POST /portfolios.