Developer Documentation

Cascade API & CLI

Integrate real-time geopolitical and economic intelligence into your applications, workflows, and AI agents.

Quick Start

Get your API key

Portal → Settings → Developer & API → Create Key

Make a request

curl -H "Authorization: Bearer csk_live_..." \
  https://cascade.metisos.co/api/v1/state

Or install the CLI

npm i -g @metisos/cascade-cli
cascade

Opens an interactive menu to configure your key and explore.

Authentication

API Keys

Authorization: Bearer csk_live_yourorg_abc123...

Formatcsk_live_{org}_{32hex}

StorageSHA-256 hashed — plaintext never stored

Rate limit60 req/min per key (default)

Permissions

readGET endpoints — state, entities, prices, correlations

writePOST/PUT/DELETE — create entities, poll sources

chatAI copilot and intelligence reports

Response Envelope

{ "data": { ... }, "meta": { "step": 4024, "timestamp": "...", "org_id": "..." } }

API Reference

Base URL: https://cascade.metisos.co

Method	Path	Perm	Description
GET	/api/v1/state	read	Simulation state — nodes, deviations, health
GET	/api/v1/events	read	Event feed (?limit=50)
GET	/api/v1/graph	read	Full graph — nodes + edges
GET	/api/v1/entities	read	List entities (?q= for search)
GET	/api/v1/entities/:name	read	Entity detail + connections + events
GET	/api/v1/entities/:name/history	read	Deviation trajectory (?steps=30)
GET	/api/v1/portfolio	read	Portfolio with risk scores
GET	/api/v1/prices	read	All tracked tickers
GET	/api/v1/prices/:entity	read	Live price history (?period=5d)
GET	/api/v1/calibration/correlations	read	Correlation matrix (?dim=1)
GET	/api/v1/calibration/lags	read	Lead/lag matrix (?dim=1)
POST	/api/v1/entities	write	Create custom entity
POST	/api/v1/portfolio	write	Add to portfolio
POST	/api/v1/sources/poll	write	Force poll all sources
POST	/api/v1/chat	chat	AI copilot query
POST	/api/v1/dossier	chat	Generate intelligence report

Examples

Get entity detail

curl -H "Authorization: Bearer $KEY" \
  https://cascade.metisos.co/api/v1/entities/Crude_Oil

Get live price

curl -H "Authorization: Bearer $KEY" \
  "https://cascade.metisos.co/api/v1/prices/SP500?period=1mo"

Ask Cascade AI

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is driving crude oil?"}' \
  https://cascade.metisos.co/api/v1/chat

Python

import requests
KEY = "csk_live_..."
BASE = "https://cascade.metisos.co/api/v1"
h = {"Authorization": f"Bearer {KEY}"}

state = requests.get(f"{BASE}/state", headers=h).json()
nodes = state["data"]["graph"]["nodes"]
for n in sorted(nodes, key=lambda n: sum(
    abs(v) for v in n["deviation_pct"]), reverse=True)[:5]:
    print(f"{n['name']:20} {n['deviation_pct']}")

CLI

npm install -g @metisos/cascade-cli
cascade config set api-key csk_live_...

cascadeInteractive welcome menu — setup, dashboard, help

cascade statusSystem health, step, entity count

cascade entitiesAll entities with deviations

cascade entity <name>Entity detail + connections

cascade eventsEvent feed (--watch for live)

cascade prices / price <entity>Live market data

cascade chat "question"Ask Cascade AI

cascade dossier --entities "X,Y"Intelligence report

cascade portfolioPortfolio with risk

cascade correlations / lagsCo-movement data

cascade skillsGenerate AI agent skills file

All commands support --format json|csv|table

AI Agent Integration

Generate a skills file so AI coding agents (Claude Code, Cursor, Copilot) can query Cascade intelligence on your behalf.

cascade skills > CASCADE_SKILLS.md

The skills file describes every command as a callable shell tool. Add it to your project:

# Claude Code — add to CLAUDE.md:
## External Tools
See CASCADE_SKILLS.md for geopolitical
intelligence commands.

# Cursor — reference in .cursorrules

Any agent that can execute shell commands can use Cascade as an intelligence layer.

Ready to integrate?

Create your API key and start querying in minutes.

Request Demo Go to Settings