API Reference

Current risk index for all five regions.

Response

{
  "status": "ok",
  "last_updated": "2026-03-23T18:45:00",
  "regions": {
    "persian_gulf": { "score": 7.4, "trend": "rising", "event_count": 18, "calculated_at": "..." },
    "hormuz":       { "score": 7.2, "trend": "stable",  "event_count": 12, "calculated_at": "..." },
    "red_sea":      { "score": 6.2, "trend": "falling", "event_count": 3,  "calculated_at": "..." },
    "oman_gulf":    { "score": 4.9, "trend": "stable",  "event_count": 10, "calculated_at": "..." },
    "bab_el_mandeb":{ "score": 5.1, "trend": "rising",  "event_count": 2,  "calculated_at": "..." }
  }
}

Example

curl https://gulfstraitsai.sxg.workers.dev/api/risk

Current risk for a single region. Valid region IDs: hormuz, bab_el_mandeb, persian_gulf, red_sea, oman_gulf.

Response

{ "score": 7.4, "trend": "rising", "event_count": 18, "calculated_at": "2026-03-23T18:45:00" }

Example

curl https://gulfstraitsai.sxg.workers.dev/api/risk/hormuz

Historical risk index entries for a region.

Response

{
  "status": "ok",
  "region": "hormuz",
  "history": [
    { "score": 7.1, "trend": "stable", "event_count": 11, "calculated_at": "2026-03-23T08:00:00" },
    ...
  ]
}

Example

curl "https://gulfstraitsai.sxg.workers.dev/api/risk/hormuz/history?hours=168"

Recent risk events (AI-classified incidents). Sorted newest-first.

Response

{
  "status": "ok",
  "events": [
    {
      "id": "a1b2c3d4",
      "event_type": "military",
      "location": "bab_el_mandeb",
      "severity": 8,
      "risk_score": 8.2,
      "summary": "Houthi forces launched drone attack on tanker in Gulf of Aden.",
      "reasoning": "Direct targeting of commercial vessel represents high-severity threat.",
      "source": "gcaptain_redsea",
      "article_url": "https://...",
      "created_at": "2026-03-23T17:30:00"
    },
    ...
  ]
}

Example

curl "https://gulfstraitsai.sxg.workers.dev/api/events?region=bab_el_mandeb&severity_min=7&limit=10"

Single event by ID.

Response

{ "status": "ok", "event": { ...full event object... } }

Example

curl https://gulfstraitsai.sxg.workers.dev/api/events/a1b2c3d4

Semantically similar past events via Cloudflare Vectorize ANN search.

Response

{
  "status": "ok",
  "event_id": "a1b2c3d4",
  "similar": [
    { ...event fields..., "similarity": 0.94 },
    ...
  ]
}

Example

curl https://gulfstraitsai.sxg.workers.dev/api/events/a1b2c3d4/similar

Subscribe to high-severity email alerts (severity ≥ 8). Welcome email sent on first subscription.

Response

{ "status": "ok", "new": true }

Example

curl -X POST https://gulfstraitsai.sxg.workers.dev/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Unsubscribe using the token included in every alert email.

Response

{ "status": "ok" }

Example

curl "https://gulfstraitsai.sxg.workers.dev/api/unsubscribe?token=<token>"

Submit public feedback. Rate-limited to 5 submissions/hour per IP.

Response

{ "status": "ok", "id": "fb123456" }

Example

curl -X POST https://gulfstraitsai.sxg.workers.dev/api/feedback \
  -H "Content-Type: application/json" \
  -d '{"message":"Great tool!", "email":"[email protected]"}'

GulfStraitsAI exposes a Model Context Protocol endpoint for AI assistant integrations. Connect any MCP-compatible client to query risk data in natural language.

# MCP endpoint
POST https://gulfstraitsai.sxg.workers.dev/mcp
Content-Type: application/json

# List available tools
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

# Call a tool
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_risk","arguments":{"region":"hormuz"}}}