Quickstart

This page takes you from no account to a signed webhook in five steps: get a key, list live signals, save a watchlist, check exposure and register a webhook. Each step is one HTTP request.

Before you start#

  • An account. Sign up in the console; new accounts start on the Sandbox plan (100 requests a month, 10 a minute, 5 watched items, no webhooks).
  • Any HTTP client. There is no SDK to install. Pick a language tab below; your choice is remembered on every page.

1. Create an API key#

In the console, open API keys and create a key. It looks like dk_live_ followed by 32 characters and is shown once. If email verification is switched on for your account, confirm your address first. Export the key so the examples can read it:

Shell
export DISRUPT_KEY="dk_live_..."

Check that it works. GET /v1/me returns your organisation, plan and key:

Request
curl "https://app.disruptapi.com/v1/me" \
  -H "Authorization: Bearer $DISRUPT_KEY"
ResponseJSON
{
  "data": {
    "org": {
      "id": "org_5c1f0a9e2b7d4c31",
      "name": "Acme Travel",
      "plan": {
        "id": "free",
        "name": "Sandbox",
        "price_usd_month": 0,
        "monthly_requests": 100,
        "per_minute": 10,
        "webhooks": 0,
        "exposure_check": true,
        "description": "100 requests a month and 5 watched items, to try the API before choosing a plan.",
        "watch_items": 5
      }
    },
    "key": { "id": "key_9a0e47c2d1b3f856", "name": "default" },
    "requests_this_month": 1
  }
}

2. Make your first request#

List the most severe active signals. Filters are optional; this asks for severe and extreme signals, five at a time:

Request
curl "https://app.disruptapi.com/v1/signals?min_severity=severe&limit=5" \
  -H "Authorization: Bearer $DISRUPT_KEY"
Response (shortened)JSON
{
  "data": [
    {
      "id": "faa_ground_stop_SEA.k3j9x2m1qa",
      "type": "aviation",
      "subtype": "ground_stop",
      "provider": "faa",
      "failure_layer": null,
      "failure_layer_label": null,
      "title": "Ground Stop Program at SEA: low ceilings",
      "severity": "severe",
      "status": "active",
      "countries": ["US"],
      "airports": ["SEA"],
      "areas": [],
      "location": { "lat": 47.449, "lon": -122.309 },
      "starts_at": null,
      "ends_at": null,
      "first_seen_at": "2026-11-18T06:52:10Z",
      "updated_at": "2026-11-18T07:20:41Z",
      "version": 2,
      "source": {
        "url": "https://nasstatus.faa.gov/",
        "attribution": "FAA NAS Status",
        "last_checked_at": "2026-11-18T07:21:02Z",
        "stale": false
      },
      "details": { "reason": "low ceilings", "End_Time": "8:30 am PST" }
    }
  ],
  "meta": { "total": 37, "limit": 5, "offset": 0 }
}

Every field is described in Signals. Results are ordered most severe first, then most recently updated.

3. Save a watchlist#

A watchlist holds the things you care about, each with your own id. Create one with its first items. Sandbox accounts can watch 5 items in total.

Request
curl -X POST "https://app.disruptapi.com/v1/watchlists" \
  -H "Authorization: Bearer $DISRUPT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Winter departures",
  "items": [
    {
      "id": "BKG-7QX2LM",
      "kind": "flight",
      "carrier": "AS",
      "origin": "SEA",
      "destination": "HNL",
      "depart_at": "2026-11-21T08:00:00Z"
    },
    {
      "id": "HTL-ALCUDIA",
      "kind": "place",
      "label": "Hotel Alcudia",
      "lat": 39.85,
      "lon": 3.12,
      "radius_km": 40
    }
  ]
}'
Response (201)JSON
{
  "data": {
    "id": "wl_3f9a1c2b7d4e5f60",
    "org_id": "org_5c1f0a9e2b7d4c31",
    "name": "Winter departures",
    "description": null,
    "created_at": "2026-11-18T08:02:11Z",
    "items_stored": 2
  }
}

To add or change items later, post them to /v1/watchlists/{id}/items. Sending an existing id replaces that item. Flights and trips are dropped a day after they end.

4. Check exposure#

Ask which active disruptions touch your items, and why. You can check a saved watchlist with GET /v1/watchlists/{id}/exposure, or send items directly, without saving them:

Request
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",
      "label": "Hotel Alcudia",
      "lat": 39.85,
      "lon": 3.12,
      "radius_km": 40
    },
    { "id": "checkout", "kind": "provider", "provider": "cloudflare" }
  ],
  "min_severity": "moderate"
}'
Response (shortened)JSON
{
  "data": [
    {
      "item_id": "BKG-7QX2LM",
      "trip_id": "BKG-7QX2LM",
      "kind": "flight",
      "risk_level": "high",
      "match_count": 1,
      "matches": [
        {
          "signal": {
            "id": "faa_ground_stop_SEA.k3j9x2m1qa",
            "type": "aviation",
            "subtype": "ground_stop",
            "provider": "faa",
            "failure_layer": null,
            "failure_layer_label": null,
            "title": "Ground Stop Program at SEA: low ceilings",
            "severity": "severe",
            "status": "active",
            "countries": ["US"],
            "airports": ["SEA"],
            "areas": [],
            "location": { "lat": 47.449, "lon": -122.309 },
            "starts_at": null,
            "ends_at": null,
            "first_seen_at": "2026-11-18T06:52:10Z",
            "updated_at": "2026-11-18T07:20:41Z",
            "version": 2,
            "source": {
              "url": "https://nasstatus.faa.gov/",
              "attribution": "FAA NAS Status",
              "last_checked_at": "2026-11-18T07:21:02Z",
              "stale": false
            },
            "details": { "reason": "low ceilings" }
          },
          "reasons": ["affects SEA"],
          "risk_contribution": "high",
          "forecast": null
        }
      ]
    },
    {
      "item_id": "HTL-ALCUDIA",
      "trip_id": "HTL-ALCUDIA",
      "kind": "place",
      "risk_level": "none",
      "match_count": 0,
      "matches": []
    },
    {
      "item_id": "checkout",
      "trip_id": "checkout",
      "kind": "provider",
      "risk_level": "none",
      "match_count": 0,
      "matches": []
    }
  ]
}

There is one result per item, in the order you sent them. risk_level is the highest risk_contribution among its matches. See Watchlists and exposure for the matching rules.

5. Receive a webhook#

Register an HTTPS endpoint. With "watchlists": ["*"] it fires only when a signal touches one of your watched items, and the payload lists those items. Webhooks need a paid plan: Starter allows 3, Pro 20.

Request
curl -X POST "https://app.disruptapi.com/v1/webhooks" \
  -H "Authorization: Bearer $DISRUPT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/disrupt",
  "filters": { "watchlists": ["*"], "min_severity": "moderate" }
}'
Response (201)JSON
{
  "data": {
    "id": "whk_8d2c41f0a6b9e357",
    "org_id": "org_5c1f0a9e2b7d4c31",
    "url": "https://example.com/webhooks/disrupt",
    "secret": "whsec_3b9f0c...",
    "filters": { "min_severity": "moderate", "watchlists": ["*"] },
    "created_at": "2026-11-18T08:05:40Z"
  }
}

Verify each delivery before you trust it. Webhooks has the verification code in eight languages and explains retries.

What next?#

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.