v1.0 — REST API
Cascade API
Programmatic access to the world's only cross-asset financial contagion signal.
BASE URLhttps://api.cascadeanalytics.ai/v1
All responses are JSON. HTTPS required. Timestamps are UTC ISO 8601. Get your API key at cascadeanalytics.ai/subscribe.
Authentication
Pass your API key in the Authorization header on every request.
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.cascadeanalytics.ai/v1/signal
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://api.cascadeanalytics.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
r = requests.get(f"{BASE}/signal", headers=headers)
print(r.json())
const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://api.cascadeanalytics.ai/v1';
const headers = { Authorization: `Bearer ${API_KEY}` };
const data = await fetch(`${BASE}/signal`, { headers })
.then(r => r.json());
console.log(data);
GET /signal
GET
/v1/signal
Current regime state & score
Returns the current Cascade signal — regime classification, composite score (0–9), and component sub-scores.
Response
{
"regime": "CAUTION",
"score": 4,
"vix_score": 1,
"breadth_score": 2,
"correlation_score": 1,
"vix_level": 22.4,
"assets_in_drawdown":7,
"avg_correlation": 0.412,
"timestamp": "2026-04-01T14:30:00Z"
}
curl -H "Authorization: Bearer $API_KEY" \
https://api.cascadeanalytics.ai/v1/signal
r = requests.get(f"{BASE}/signal", headers=headers)
s = r.json()
print(f"Regime: {s['regime']} — Score: {s['score']}/9")
const s = await fetch(`${BASE}/signal`,{headers}).then(r=>r.json());
console.log(`${s.regime} — ${s.score}/9`);
GET /regime
GET
/v1/regime
Regime classification history
Returns daily regime history. Useful for backtesting integrations and risk reporting.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | integer | 90 | History window (max 365) |
| interval | string | daily | daily or weekly |
{
"interval": "daily", "days": 90,
"history": [
{ "date": "2026-04-01", "regime": "CAUTION", "score": 4 },
{ "date": "2026-03-31", "regime": "SAFE", "score": 2 }
]
}
GET /alerts
GET
/v1/alerts
Historical alert log
Returns the log of regime alert events — when each alert triggered and resolved.
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 20 | Max results (max 100) |
| since | string | — | ISO date filter e.g. 2025-01-01 |
{
"alerts": [{
"alert_id": "alrt_20260401",
"triggered_at":"2026-04-01T09:30:00Z",
"regime": "CAUTION",
"score": 4,
"resolved_at": null,
"duration_days":null
}]
}
GET /historical
GET
/v1/historical
15 crisis detections (2008–2025)
The full V6 backtest dataset. 15/15 crises detected. Average lead time 29 days.
{
"detection_rate": "15/15",
"avg_lead_days": 29,
"crises": [
{"name":"COVID Crash", "date":"2020-02-19", "lead_days":44, "oos":true},
{"name":"Bear Stearns", "date":"2008-03-14", "lead_days":45, "oos":false},
{"name":"Tariff Shock 2025","date":"2025-02-19", "lead_days":40, "oos":true}
]
}
GET /assets
GET
/v1/assets
12-asset stress snapshot
Current price, change, drawdown, and stress level for all 12 tracked assets: SPY, QQQ, IWM, HYG, LQD, TLT, IEF, EEM, GLD, DBC, XLF, EWA.
{
"timestamp": "2026-04-01T14:30:00Z",
"assets": [{
"ticker": "GLD",
"name": "Gold ETF",
"price_usd": 283.47,
"change_1d_pct": +0.82,
"drawdown_30d_pct":-0.4,
"stress_level": "CALM"
}]
}
curl -H "Authorization: Bearer $API_KEY" \
https://api.cascadeanalytics.ai/v1/assets
r = requests.get(f"{BASE}/assets", headers=headers)
for a in r.json()["assets"]:
print(f"{a['ticker']:4s} {a['stress_level']:10s} ${a['price_usd']}")
const {assets} = await fetch(`${BASE}/assets`,{headers}).then(r=>r.json());
assets.forEach(a => console.log(`${a.ticker}: ${a.stress_level} $${a.price_usd}`));
Webhooks
Push notifications when regime changes. No polling required.
Setup: POST
{"url": "https://your-server.com/hook"} to POST /v1/webhooks.Event Types
regime.changed— regime classification shiftedalert.triggered— entered DANGER or EXTREMEalert.resolved— returned to SAFE or CAUTION
Payload
{
"event_type": "regime.changed",
"timestamp": "2026-04-01T09:30:00Z",
"data": {
"previous_regime": "CAUTION",
"current_regime": "DANGER",
"score": 6
}
}
Verification
Every request includes X-Cascade-Signature — HMAC-SHA256 of the raw body signed with your webhook secret.
import hmac, hashlib
from flask import Flask, request
app = Flask(__name__)
SECRET = "your_webhook_secret"
@app.route("/hook", methods=["POST"])
def hook():
sig = request.headers.get("X-Cascade-Signature", "")
expected = hmac.new(SECRET.encode(), request.data, hashlib.sha256).hexdigest()
if not hmac.compare_digest(sig, expected):
return "Unauthorized", 401
payload = request.json()
# handle regime change...
return "", 200
const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = 'your_webhook_secret';
app.post('/hook', express.raw({type:'*/*'}), (req,res) => {
const sig = req.headers['x-cascade-signature'];
const expected = crypto.createHmac('sha256',SECRET).update(req.body).digest('hex');
if (sig !== expected) return res.sendStatus(401);
const ev = JSON.parse(req.body);
// handle...
res.sendStatus(200);
});
Retry policy: 3 attempts — 30s, 5min, 30min exponential backoff. Your endpoint must return 2xx.
Rate Limits
| Tier | Daily Requests | Burst |
|---|---|---|
| Signal Access | 1,000 / day | 10 / second |
| Parametric Engine | 10,000 / day | 50 / second |
| Enterprise | Unlimited | Unlimited |
Response headers:
X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-ResetSDKs
Native client libraries with full type support, automatic retries, and Pandas/tidyverse integrations.
Python
Async support. Pandas integration for time-series workflows.
pip install cascade-analytics
Q3 2026
R
tidyverse-native. Built for actuarial and statistical analysis.
install.packages("cascadeanalytics")
Q3 2026
JavaScript
TypeScript types included. Works in browser and Node.js.
npm i @cascade-analytics/sdk
Q3 2026
Early access: Request SDK beta when you sign up at cascadeanalytics.ai/subscribe.
Error Codes
All error responses include error (machine key) and message (human readable) fields.
| Code | Status | Cause |
|---|---|---|
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Endpoint requires higher subscription tier |
| 404 | Not Found | Endpoint does not exist |
| 429 | Rate Limited | Daily request quota exceeded |
| 500 | Server Error | Internal error — retry with exponential backoff |
{
"error": "rate_limit_exceeded",
"message": "Daily quota of 1,000 requests exceeded. Resets 2026-04-02T00:00:00Z.",
"reset_at":"2026-04-02T00:00:00Z"
}
Changelog
v1.0
Q1 2026
Initial release.
/signal /regime /alerts /historical /assets — REST + API key auth.
v1.1
Q2 2026
Coming SoonWebhook support. Portfolio scoring endpoint. 5-year regime history.
v2.0
Q3 2026
Coming SoonPython, R & JS SDK releases. Streaming API. Custom basket endpoint.