Hydra
Docs

The envelope and structure of all WebSocket messages.

Message Format

All server-to-client messages follow a simple two-field envelope.

Server → Client Envelope

interface HydraMessage {
  type: string    // event type (e.g. 'aircraft', 'signal', 'connected')
  data: unknown   // payload — shape depends on type
}

Data Message

{
  "type": "signal",
  "data": {
    "signals": [
      { "id": "clxxx", "title": "...", "severity": 4 }
    ]
  }
}

Control Message

{
  "type": "connected",
  "data": {
    "scopes": ["signals", "aircraft"],
    "ts": 1710000000000
  }
}

All Event Types

type Description Scope
connected Connection confirmed with scopes —
error Auth or server error —
aircraft Aircraft position update or snapshot aircraft
vessel Vessel position update or snapshot vessels
signal Intelligence signal (new or batch) signals / alerts / airspace / cyber / earthquakes
alert Missile/rocket alert update alerts
market Prediction market data markets
market_correlation Signal–market correlation markets
x_post Social media OSINT post social
tension Country tension level update — (internal)
chat_message Live chat message — (internal)
chat_history Chat history snapshot on connect — (internal)
online_count Connected user count — (internal)

Types marked "internal" are only sent on the /stream/live endpoint.

Snapshot Payloads

On connect, the server sends the current state for each scope. Snapshot messages use the same type as live updates but contain arrays:

Aircraft snapshot:

{
  "type": "aircraft",
  "data": {
    "positions": [
      {
        "icaoHex": "AE1234", "callsign": "FORGE11",
        "lat": 32.5, "lng": 35.1, "altitudeBaro": 28000,
        "groundSpeed": 450, "track": 180,
        "isMilitary": true, "operator": "USAF",
        "timestamp": "2025-03-20T12:00:00.000Z"
      }
    ],
    "count": 1,
    "timestamp": "2025-03-20T12:00:00.000Z"
  }
}

Signal snapshot:

{
  "type": "signal",
  "data": {
    "signals": [
      { "id": "clxxx", "title": "...", "category": "CYBER", "severity": 4 }
    ]
  }
}

Vessel snapshot:

{
  "type": "vessel",
  "data": {
    "positions": [
      {
        "mmsi": "123456789", "name": "VESSEL NAME",
        "lat": 33.1, "lng": 34.2, "speed": 12.5,
        "course": 270, "shipType": "Cargo",
        "timestamp": 1710000000000
      }
    ],
    "count": 1,
    "timestamp": "2025-03-20T12:00:00.000Z"
  }
}

Error Messages

{
  "type": "error",
  "data": {
    "message": "Unauthorized — provide a valid API key via ?apiKey= or x-api-key header"
  }
}

Error messages are sent before the connection is closed with the appropriate close code.

Client → Server

The Hydra WebSocket is server-push only — there are no client-to-server commands. Scope filtering is configured via your API key, not runtime messages. The server does respond to WebSocket protocol-level pong frames for keep-alive.