Developers

Blit Pro API

Bearer access for robots, Zapier, and custom desks. Read GRI, feed, market, and manage a light watchlist — keys live in Settings → Integrations.

Create API key Open Pro desk OpenAPI JSON

Quickstart

Base URL: https://core.intelligence-desk.com. Authenticate every /api/v1/key/* call with Authorization: Bearer bt_…

Pro rate limit defaults to 1000 requests per minute. Check GET /api/v1/key/account/usage for your plan limits.

All paths below require a Pro API key. Alert rules, webhook CRUD, and web push stay in the desk UI.

Authentication

Create a key in the Pro desk under Settings → Integrations. The secret is shown once — store it in a secrets manager and never commit it.

Common error codes:

401 — missing or invalid key
402 — active Pro subscription required
403 — plan feature not enabled
422 — validation failed
429 — rate limit exceeded

Request

curl -sS "https://core.intelligence-desk.com/api/v1/key/risk" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Risk

Live Global Risk Index, components, history, drivers, and multi-window deltas.

GET/api/v1/key/risk

Current GRI

Latest Global Risk Index snapshot with component scores.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/risk" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "value": 52.4,
  "confidence": 0.82,
  "components": [
    {
      "component": "conflict",
      "score": 61.2,
      "weight": 0.28
    },
    {
      "component": "sanctions",
      "score": 48,
      "weight": 0.18
    },
    {
      "component": "energy",
      "score": 55.5,
      "weight": 0.22
    }
  ],
  "metadata": {
    "method": "gri_v1"
  },
  "recorded_at": "2026-07-31T18:00:00+00:00"
}

GET/api/v1/key/risk/components?hours=24

Component series

Per-component score history for the last N hours (default 24, max 720).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/risk/components?hours=24" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "components": {
    "conflict": [
      {
        "recorded_at": "2026-07-31T12:00:00+00:00",
        "score": 58.1
      },
      {
        "recorded_at": "2026-07-31T18:00:00+00:00",
        "score": 61.2
      }
    ],
    "energy": [
      {
        "recorded_at": "2026-07-31T12:00:00+00:00",
        "score": 52
      },
      {
        "recorded_at": "2026-07-31T18:00:00+00:00",
        "score": 55.5
      }
    ]
  }
}

GET/api/v1/key/risk/history?hours=48&events=1

GRI history

Point-in-time GRI series. Set events=1 to include high-severity wires in the window.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/risk/history?hours=48&events=1" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "hours": 48,
  "history": [
    {
      "recorded_at": "2026-07-30T18:00:00+00:00",
      "value": 47.2,
      "confidence": 0.78
    },
    {
      "recorded_at": "2026-07-31T18:00:00+00:00",
      "value": 52.4,
      "confidence": 0.82
    }
  ],
  "events": [
    {
      "id": "9f1e2a3b-0000-4000-8000-000000000001",
      "title": "Strait shipping disruption",
      "severity": 0.88,
      "region": "MENA",
      "event_type": "conflict",
      "occurred_at": "2026-07-31T14:20:00+00:00"
    }
  ]
}

GET/api/v1/key/risk/drivers?hours=4

Risk drivers

Events contributing most to the recent GRI move, plus component deltas.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/risk/drivers?hours=4" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "hours": 4,
  "current": {
    "value": 52.4,
    "confidence": 0.82,
    "recorded_at": "2026-07-31T18:00:00+00:00"
  },
  "delta": {
    "value": 3.1,
    "components": {
      "conflict": 2.4,
      "energy": 1.1,
      "sanctions": -0.4
    }
  },
  "drivers": [
    {
      "id": "9f1e2a3b-0000-4000-8000-000000000001",
      "title": "Strait shipping disruption",
      "event_type": "conflict",
      "region": "MENA",
      "severity": 0.88,
      "confidence": 0.81,
      "occurred_at": "2026-07-31T14:20:00+00:00",
      "contribution": 0.612
    }
  ]
}

GET/api/v1/key/risk/delta?windows=1,4,24

Multi-window delta

GRI change across windows (default 1h, 4h, 24h).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/risk/delta?windows=1,4,24" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "windows": {
    "1h": {
      "value": 0.6,
      "from": 51.8,
      "to": 52.4
    },
    "4h": {
      "value": 3.1,
      "from": 49.3,
      "to": 52.4
    },
    "24h": {
      "value": 5.2,
      "from": 47.2,
      "to": 52.4
    }
  }
}

Feed

Full cited briefings (not public teasers). Pass locale=en|pt|es.

GET/api/v1/key/feed?locale=en&per_page=20

List briefings

Paginated Pro briefings for a locale.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/feed?locale=en&per_page=20" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "current_page": 1,
  "per_page": 20,
  "total": 42,
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000010",
      "slug": "strait-pressure-oil-tape",
      "title": "Strait pressure hits the oil tape",
      "locale": "en",
      "published_at": "2026-07-31T16:40:00+00:00",
      "summary": "Cited dossier on shipping risk and WTI reaction."
    }
  ]
}

GET/api/v1/key/feed/{idOrSlug}?locale=en

Show briefing

Full dossier by id or slug. Falls back to a sibling locale when needed.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/feed/strait-pressure-oil-tape?locale=en" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "id": "a1b2c3d4-0000-4000-8000-000000000010",
  "slug": "strait-pressure-oil-tape",
  "title": "Strait pressure hits the oil tape",
  "locale": "en",
  "body": "Full cited briefing body…",
  "published_at": "2026-07-31T16:40:00+00:00",
  "citations": [
    {
      "url": "https://example.com/wire",
      "title": "Wire source"
    }
  ]
}

Search

Full-text search across geopolitical events and briefings.

GET/api/v1/key/search?q=hormuz&type=all&limit=10

Search

Query events and articles. type=all|events|articles.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/search?q=hormuz&type=all&limit=10" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "query": "hormuz",
  "results": {
    "events": [
      {
        "id": "9f1e2a3b-0000-4000-8000-000000000001",
        "title": "Strait shipping disruption",
        "region": "MENA",
        "severity": 0.88
      }
    ],
    "articles": [
      {
        "id": "a1b2c3d4-0000-4000-8000-000000000010",
        "slug": "strait-pressure-oil-tape",
        "title": "Strait pressure hits the oil tape"
      }
    ]
  }
}

Market

Correlations and surprise readings of GRI vs the tape.

GET/api/v1/key/market/correlations?days=30

Correlations

Pearson correlation of event severity vs oil returns over N days.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/market/correlations?days=30" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "period_days": 30,
  "event_count": 86,
  "price_points": 720,
  "paired_count": 64,
  "correlation": 0.41,
  "avg_severity": 0.62,
  "avg_oil_change": 0.18,
  "window_hours": 4,
  "symbol": "WTI",
  "method": "pearson_severity_vs_oil_return",
  "caveat": "Illustrative pairing; not investment advice."
}

GET/api/v1/key/market/surprise?window=1h

Surprise panel

Compare GRI delta to WTI/Brent/DXY moves for window=1h|4h.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/market/surprise?window=1h" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "window": "1h",
  "hours": 1,
  "gri_delta": 2.4,
  "markets": {
    "WTI": {
      "label": "WTI",
      "delta_percent": 0.12
    },
    "Brent": {
      "label": "Brent",
      "delta_percent": 0.09
    },
    "DXY": {
      "label": "DXY",
      "delta_percent": -0.04
    }
  },
  "reading": "gri_up_oil_flat",
  "summary": "GRI rose while oil barely moved — tape may be lagging.",
  "thresholds": {
    "gri_move": 2,
    "oil_move": 0.5
  },
  "method": "delta_compare",
  "caveat": "Heuristic reading; not investment advice."
}

Watchlist

Pin regions, entities, or symbols. Optional alert thresholds on each pin.

GET/api/v1/key/watch-items

List watch items

Tenant pins with enrichment (recent events or live quote).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/watch-items" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "data": [
    {
      "id": "w1111111-0000-4000-8000-000000000001",
      "watchable_type": "region",
      "watchable_key": "mena",
      "label": "Middle East",
      "alerts_enabled": true,
      "alert_threshold": 70,
      "alert_channels": [
        "email",
        "webhook"
      ],
      "enrichment": {
        "max_severity": 88,
        "recent_events": [
          {
            "title": "Strait shipping disruption",
            "severity": 88
          }
        ]
      }
    }
  ]
}

POST/api/v1/key/watch-items

Create watch item

type=region|entity|symbol. Keys are normalized (regions lowercased, symbols uppercased).

Request

curl -sS -X POST "https://core.intelligence-desk.com/api/v1/key/watch-items" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"type":"region","key":"MENA","label":"Middle East","alerts_enabled":true,"alert_threshold":70,"alert_channels":["email","webhook"],"cooldown_minutes":60}'

Response201

{
  "id": "w1111111-0000-4000-8000-000000000001",
  "watchable_type": "region",
  "watchable_key": "mena",
  "label": "Middle East",
  "alerts_enabled": true,
  "alert_threshold": 70,
  "alert_channels": [
    "email",
    "webhook"
  ],
  "cooldown_minutes": 60,
  "created_at": "2026-07-31T18:05:00+00:00"
}

PATCH/api/v1/key/watch-items/{id}

Update watch item

Patch label and alert settings (threshold, channels, cooldown).

Request

curl -sS -X PATCH "https://core.intelligence-desk.com/api/v1/key/watch-items/w1111111-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"label":"MENA desk","alerts_enabled":true,"alert_threshold":75,"alert_channels":["email","web_push","webhook"],"cooldown_minutes":120}'

Response200

{
  "id": "w1111111-0000-4000-8000-000000000001",
  "watchable_type": "region",
  "watchable_key": "mena",
  "label": "MENA desk",
  "alerts_enabled": true,
  "alert_threshold": 75,
  "alert_channels": [
    "email",
    "web_push",
    "webhook"
  ],
  "cooldown_minutes": 120
}

DELETE/api/v1/key/watch-items/{id}

Delete watch item

Remove a pin from the tenant watchlist.

Request

curl -sS -X DELETE "https://core.intelligence-desk.com/api/v1/key/watch-items/w1111111-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "message": "Deleted."
}

POST/api/v1/key/watch-items/from-driver

Pin from driver

Create a region pin from a geopolitical event id (uses the event region).

Request

curl -sS -X POST "https://core.intelligence-desk.com/api/v1/key/watch-items/from-driver" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"9f1e2a3b-0000-4000-8000-000000000001"}'

Response201

{
  "id": "w2222222-0000-4000-8000-000000000002",
  "watchable_type": "region",
  "watchable_key": "mena",
  "label": "MENA",
  "meta": {
    "source": "driver",
    "event_id": "9f1e2a3b-0000-4000-8000-000000000001"
  },
  "alerts_enabled": false,
  "created_at": "2026-07-31T18:06:00+00:00"
}

Account

Plan features, rate limits, and approximate usage counts for the calling key.

GET/api/v1/key/account/usage

Account usage

Plan, feature flags, rate limits, resource caps, and counts for the authenticated key.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/key/account/usage" \
  -H "Authorization: Bearer bt_YOUR_KEY" \
  -H "Accept: application/json"

Response200

{
  "plan": "pro",
  "status": "active",
  "features": [
    "detailed_risk",
    "live_briefings",
    "watchlist",
    "api_keys"
  ],
  "rate_limits": {
    "requests": 1000,
    "per_minutes": 1
  },
  "limits": {
    "alert_rule_limit": 200,
    "watch_item_limit": 25
  },
  "usage": {
    "alert_rules": 4,
    "watch_items": 7,
    "api_keys": 2
  },
  "api_key": {
    "id": "k3333333-0000-4000-8000-000000000003",
    "prefix": "bt_AbCdEfGh",
    "last_used_at": "2026-07-31T18:07:00+00:00"
  }
}

Outbound webhooks

Configure delivery URLs in Settings → Integrations. When an alert fires, Blit POSTs alert.triggered to your endpoint.

Verify HMAC: signed payload is "{timestamp}.{rawBody}" with your whsec_… secret.

Delivery headers

POST /your-endpoint HTTP/1.1
Content-Type: application/json
X-Blit-Timestamp: 1710000000
X-Blit-Signature: v1=<hmac_sha256("{ts}.{rawBody}", secret)>

Payload · GRI alert

{
  "type": "alert.triggered",
  "alert_event_id": "ae444444-0000-4000-8000-000000000004",
  "rule": {
    "id": "ar555555-0000-4000-8000-000000000005",
    "name": "GRI spike",
    "type": "delta"
  },
  "watch_item": null,
  "payload": {
    "gri": {
      "value": 58.2,
      "delta_4h": 6.1
    }
  },
  "triggered_at": "2026-07-31T18:10:00+00:00"
}

Payload · watchlist alert

{
  "type": "alert.triggered",
  "alert_event_id": "ae666666-0000-4000-8000-000000000006",
  "rule": null,
  "watch_item": {
    "id": "w1111111-0000-4000-8000-000000000001",
    "watchable_type": "region",
    "watchable_key": "mena",
    "label": "Middle East"
  },
  "payload": {
    "severity": 88,
    "title": "Strait shipping disruption"
  },
  "triggered_at": "2026-07-31T18:12:00+00:00"
}

Open Integrations settings

Public teaser API

No auth required for /api/v1/public/* (GRI teaser, feed teasers, events, gadget, market quotes). Full dossiers and drivers need Pro.

Cached, rate-limited teaser surface for the portal. Events are delayed ~30 minutes. Feed returns teasers only — not full dossiers.

GET/api/v1/public/risk

Current GRI (public)

Latest published GRI with band label/tone. No component breakdown.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/risk" \
  -H "Accept: application/json"

Response200

{
  "value": 52.4,
  "confidence": 0.82,
  "band": {
    "label": "Watch",
    "tone": "watch"
  },
  "recorded_at": "2026-07-31T18:00:00+00:00"
}

GET/api/v1/public/risk/history?hours=24

GRI history (public)

Downsampled sparkline history. hours=1…24 (default 24).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/risk/history?hours=24" \
  -H "Accept: application/json"

Response200

{
  "history": [
    {
      "recorded_at": "2026-07-30T18:00:00+00:00",
      "value": 47.2,
      "confidence": 0.78
    },
    {
      "recorded_at": "2026-07-31T18:00:00+00:00",
      "value": 52.4,
      "confidence": 0.82
    }
  ]
}

GET/api/v1/public/events?per_page=5

List events

Paginated geopolitical events older than the 30-minute public delay. per_page max 10.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/events?per_page=5" \
  -H "Accept: application/json"

Response200

{
  "current_page": 1,
  "per_page": 5,
  "total": 120,
  "data": [
    {
      "id": "9f1e2a3b-0000-4000-8000-000000000001",
      "title": "Strait shipping disruption",
      "summary": "Escalation near critical transit lanes.",
      "severity": 0.88,
      "confidence": 0.81,
      "region": "MENA",
      "event_type": "conflict",
      "sentiment": -0.42,
      "occurred_at": "2026-07-31T14:20:00+00:00"
    }
  ]
}

GET/api/v1/public/events/{id}

Show event

Event detail with entities and linked public article (if any).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/events/9f1e2a3b-0000-4000-8000-000000000001" \
  -H "Accept: application/json"

Response200

{
  "id": "9f1e2a3b-0000-4000-8000-000000000001",
  "title": "Strait shipping disruption",
  "summary": "Escalation near critical transit lanes.",
  "severity": 0.88,
  "confidence": 0.81,
  "region": "MENA",
  "event_type": "conflict",
  "sentiment": -0.42,
  "occurred_at": "2026-07-31T14:20:00+00:00",
  "entities": [
    {
      "id": "e7777777-0000-4000-8000-000000000007",
      "name": "Iran",
      "type": "country",
      "pivot": {
        "role": "actor"
      }
    }
  ],
  "public_article": {
    "id": "a1b2c3d4-0000-4000-8000-000000000010",
    "slug": "strait-pressure-oil-tape",
    "title": "Strait pressure hits the oil tape",
    "status": "published"
  }
}

GET/api/v1/public/feed?locale=en&per_page=20

List feed teasers

Paginated briefing teasers for locale=en|pt|es. Body/citations stay on Pro.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/feed?locale=en&per_page=20" \
  -H "Accept: application/json"

Response200

{
  "current_page": 1,
  "per_page": 20,
  "total": 18,
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000010",
      "slug": "strait-pressure-oil-tape",
      "title": "Strait pressure hits the oil tape",
      "summary": "Shipping risk lifts the public tape…",
      "locale": "en",
      "published_at": "2026-07-31T16:40:00+00:00",
      "confidence": 0.78,
      "metadata": {
        "severity": 0.88,
        "region": "MENA",
        "event_type": "conflict",
        "source_count": 4,
        "origin": "briefing"
      },
      "teaser": true
    }
  ]
}

GET/api/v1/public/feed/{idOrSlug}?locale=en

Show feed teaser

Single teaser by id or slug. Not the full Pro dossier.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/feed/strait-pressure-oil-tape?locale=en" \
  -H "Accept: application/json"

Response200

{
  "id": "a1b2c3d4-0000-4000-8000-000000000010",
  "slug": "strait-pressure-oil-tape",
  "title": "Strait pressure hits the oil tape",
  "summary": "Shipping risk lifts the public tape…",
  "locale": "en",
  "published_at": "2026-07-31T16:40:00+00:00",
  "confidence": 0.78,
  "metadata": {
    "severity": 0.88,
    "region": "MENA",
    "event_type": "conflict",
    "source_count": 4,
    "origin": "briefing"
  },
  "teaser": true
}

GET/api/v1/public/gadget

Gadget payload

Compact chip payload: risk value, band, and three recent delayed events.

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/gadget" \
  -H "Accept: application/json"

Response200

{
  "risk_value": 52.4,
  "risk_label": "watch",
  "band": {
    "label": "Watch",
    "tone": "watch"
  },
  "recent_events": [
    {
      "id": "9f1e2a3b-0000-4000-8000-000000000001",
      "title": "Strait shipping disruption",
      "severity": 0.88,
      "region": "MENA"
    }
  ],
  "updated_at": "2026-07-31T18:00:00+00:00"
}

GET/api/v1/public/market/quotes

Market quotes

Latest tape quotes for configured symbols (exchanges + risk assets).

Request

curl -sS -X GET "https://core.intelligence-desk.com/api/v1/public/market/quotes" \
  -H "Accept: application/json"

Response200

{
  "quotes": [
    {
      "symbol": "WTI",
      "label": "WTI Crude",
      "unit": "USD/bbl",
      "group": "risk_assets",
      "price": 81.25,
      "change_percent": 0.42,
      "recorded_at": "2026-07-31T18:00:00+00:00",
      "source": "db"
    },
    {
      "symbol": "SPX",
      "label": "S&P 500",
      "unit": "pts",
      "group": "exchanges",
      "price": 5482.1,
      "change_percent": -0.18,
      "recorded_at": "2026-07-31T18:00:00+00:00",
      "source": "db"
    }
  ]
}

Methodology · Plans