From API key to first alert in ten minutes
A REST API with JSON bodies, bearer keys, an OpenAPI spec and HMAC-signed webhooks. These steps cover everything most integrations need, and an MCP server gives AI assistants the same data.
1. Authenticate
Create a key in the console. Send it as a bearer token, or in the X-API-Key header. Keys are shown once and stored hashed.
Every response carries X-RateLimit-* and X-Quota-* headers. Errors always look like {"error": {"code", "message"}}.
curl https://app.disruptapi.com/v1/signals?min_severity=severe \
-H "Authorization: Bearer $DISRUPT_KEY"2. Check exposure
Send the things you care about. Each item has your own id and a kind: flight, trip (with legs), place (airport, lat/lon with radius, or country), carrier or provider. Leave out the kind and DisruptAPI infers it.
{
"data": [{
"item_id": "BKG-7QX2LM",
"kind": "flight",
"risk_level": "high",
"match_count": 1,
"matches": [{
"signal": {
"id": "faa_ground_stop_SEA",
"type": "aviation",
"subtype": "ground_stop",
"title": "Ground Stop at SEA: low ceilings",
"severity": "severe",
"airports": ["SEA"],
"starts_at": "2026-11-21T06:52:00Z",
"source": { "attribution": "FAA NAS Status" }
},
"reasons": ["affects SEA"],
"risk_contribution": "high"
}]
}]
}curl -X POST https://app.disruptapi.com/v1/exposure/check \
-H "Authorization: Bearer $DISRUPT_KEY" \
-H "Content-Type: application/json" \
-d '{ "items": [ { "id": "BKG-7QX2LM", "kind": "flight", "carrier": "AS", "origin": "SEA", "destination": "HNL", "depart_at": "2026-11-21T08:00:00Z" }, { "id": "HTL-ALCUDIA", "kind": "place", "lat": 39.85, "lon": 3.12, "radius_km": 40 }, { "id": "checkout", "kind": "provider", "provider": "cloudflare" } ] }'import os, requests
items = [
{"id": "BKG-7QX2LM", "kind": "flight", "carrier": "AS",
"origin": "SEA", "destination": "HNL", "depart_at": "2026-11-21T08:00:00Z"},
{"id": "checkout", "kind": "provider", "provider": "cloudflare"},
]
r = requests.post(
"https://app.disruptapi.com/v1/exposure/check",
headers={"Authorization": f"Bearer {os.environ['DISRUPT_KEY']}"},
json={"items": items, "min_severity": "moderate"},
)
for result in r.json()["data"]:
print(result["item_id"], result["risk_level"], result["match_count"])const res = await fetch("https://app.disruptapi.com/v1/exposure/check", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DISRUPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{ id: "BKG-7QX2LM", kind: "flight", carrier: "AS",
origin: "SEA", destination: "HNL", depart_at: "2026-11-21T08:00:00Z" },
],
}),
});
const { data } = await res.json();
console.log(data.filter((r) => r.risk_level !== "none"));3. Keep a watchlist in sync
Create a watchlist once, then post items to it whenever a booking is made or changed. Sending an existing id updates it. Flights and trips drop off a day after they end; places, carriers and providers stay until you remove them.
# create a watchlist
curl -X POST https://app.disruptapi.com/v1/watchlists \
-H "Authorization: Bearer $DISRUPT_KEY" -H "Content-Type: application/json" \
-d '{"name": "Winter departures"}'
# add or update items by your own id
curl -X POST https://app.disruptapi.com/v1/watchlists/wl_.../items \
-H "Authorization: Bearer $DISRUPT_KEY" -H "Content-Type: application/json" \
-d '{"items": [{"id": "BKG-7QX2LM", "carrier": "AS", "origin": "SEA",
"destination": "HNL", "depart_at": "2026-11-21T08:00:00Z"}]}'
# what is exposed right now
curl https://app.disruptapi.com/v1/watchlists/wl_.../exposure -H "Authorization: Bearer $DISRUPT_KEY"4. Receive webhooks
Register an https endpoint with filters: types, minimum severity, countries, airports, or "watchlists": ["*"] to hear only about disruptions that touch your items. Events are signal.created, .escalated, .updated and .resolved, or exposure.* with the affected items attached.
Each delivery carries a Disrupt-Signature: t=…,v1=… header: an HMAC-SHA256 of the timestamp and the raw body. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours.
import hashlib, hmac, time
def verify(secret: str, body: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256)
return hmac.compare_digest(mac.hexdigest(), parts["v1"])5. Optional: connect your AI assistant over MCP
DisruptAPI runs a remote Model Context Protocol server at /mcp. Connect it to Claude, Cursor, VS Code or your own agent and ask in plain words: “Is anything going to hit our Frankfurt departures tomorrow?” The assistant calls the same exposure check, signals and forecasts as the REST API.
It uses your API key, your plan and your rate limits. Each tool call counts as one request and shows in your usage. The server speaks Streamable HTTP, protocol versions 2024-11-05 to 2025-06-18.
claude mcp add --transport http disrupt https://app.disruptapi.com/mcp \
--header "Authorization: Bearer $DISRUPT_KEY"// ~/.cursor/mcp.json
{
"mcpServers": {
"disrupt": {
"url": "https://app.disruptapi.com/mcp",
"headers": { "Authorization": "Bearer ${env:DISRUPT_KEY}" }
}
}
}// .vscode/mcp.json
{
"servers": {
"disrupt": {
"type": "http",
"url": "https://app.disruptapi.com/mcp",
"headers": { "Authorization": "Bearer ${env:DISRUPT_KEY}" }
}
}
}// claude_desktop_config.json, through the mcp-remote bridge
{
"mcpServers": {
"disrupt": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.disruptapi.com/mcp",
"--header", "Authorization:${DISRUPT_AUTH}"],
"env": { "DISRUPT_AUTH": "Bearer dk_live_..." }
}
}
}Endpoints at a glance
| Method | Path | What it returns |
|---|---|---|
| POST | /v1/exposure/check | For a list of items: the disruptions that touch each one, why, a risk level and a forecast. |
| GET/POST | /v1/watchlists | Saved lists of items that are re-checked against every new signal. |
| POST | /v1/watchlists/{id}/items | Add or update items by your own id. Up to your plan's item limit. |
| GET | /v1/watchlists/{id}/exposure | The items on a watchlist that are exposed right now. |
| GET | /v1/signals | Live signals. Filter by type, min_severity, country, airport, provider, since and status. |
| GET | /v1/signals/{id} | One signal with its impact forecast. |
| GET | /v1/forecast | What history says an outage of a given provider and failure layer does to travel. |
| GET | /v1/airports/{iata} | Active signals at and around an airport, monthly base rates and website dependencies. |
| GET | /v1/carriers/{code} | What an airline's public systems run on, outages that put it at risk, and past events. |
| GET | /v1/providers | Watched cloud and SaaS providers and whether they have an incident now. |
| GET | /v1/events | The catalogue of past disruptions and their measured outcomes. |
| GET/POST | /v1/webhooks | Signed push notifications when matching signals start, escalate, change or resolve. |
Parameters, schemas and examples for every endpoint are in the API reference.
Tools your assistant gets
| Tool | What it answers |
|---|---|
| check_exposure | Which of these flights, trips, places, carriers or providers are hit, why, and how badly. |
| list_signals | Live disruptions, filtered by type, severity, country, airport or provider. |
| get_signal | One disruption with its impact forecast. |
| get_forecast | What-if: what an outage of a provider and failure layer would do to travel. |
| get_airport | Everything active at and around an airport, plus monthly base rates. |
| get_carrier | What an airline’s systems run on and which outages put it at risk. |
| list_providers | Watched cloud and SaaS providers and whether they have an incident. |
| list_events | Past disruptions and their measured outcomes. |
| create_watchlist · add_watchlist_items · remove_watchlist_item | Keep a saved list of items in sync. |
| list_watchlists · get_watchlist · get_watchlist_exposure | Read saved lists and what is exposed right now. |
Your key is one sign-up away
A sandbox key covers 100 requests a month and 5 watched items, enough to wire up exposure checks before you choose a plan.