WebSocket overview

The WebSocket interface complements the REST API with server-pushed updates. Use it whenever your UI needs to react to changes without polling.

Endpoints

Endpoint	Channel
wss://api.scorelytics.pro/v1/ws/match/{id}	One match.
wss://api.scorelytics.pro/v1/ws/live	All live matches across all your tracked leagues.

Both speak the same JSON message format.

Authentication

WebSocket browsers do not let you set headers, so authenticate via the query parameter:

wss://api.scorelytics.pro/v1/ws/live?api_key=sk_live_...

Server-side clients can use the header — X-API-Key: sk_live_... works fine over WebSocket too.

Message format

Every message is a JSON object with three top-level fields:

{
  "type": "score_update",
  "match_id": "abc123",
  "data": { /* type-specific */ }
}

type	When it fires	data shape
score_update	Score, period, minute or game clock changed.	{ home, away, minute? }
status_change	Lifecycle status changed.	{ from, to } (status codes)

Future event types (e.g. event_added for goals/cards) will be added backwards-compatibly.

Don't bootstrap from WebSocket alone

Always:

1. Fetch a REST snapshot first.
2. Then open the WebSocket.
3. Apply each WS message as a delta on top of the snapshot.

This is the only way to guarantee your UI starts coherent — see the live scoreboard guide for the full pattern.

Connection lifecycle

Phase	What you should do
open	Mark UI as live.
message	Apply delta, re-render.
error	Log and let close handle reconnection.
close	Reconnect with exponential backoff (cap at 30 s). On reconnect, re-fetch the REST snapshot first.

Pings

We send a server-side ping every 30 seconds. If your client doesn't respond to two consecutive pings, the connection is closed. Standard browser WebSocket APIs handle this transparently; if you build a custom client, respond to pings within the 30 s window.

Limits

• Up to 5 concurrent WebSocket connections per API key (default plan).
• Connections idle for >30 s without server-side activity are kept alive via pings — there is no idle-timeout disconnect for /v1/ws/live.

Need higher concurrency? Email support@scorelytics.pro.

Choosing the right endpoint

Use case	Endpoint
Single-match scoreboard.	/v1/ws/match/{id}
Multi-match dashboard.	One WS per match (preferred) or one global /v1/ws/live and filter client-side.
Notifications across all live matches.	/v1/ws/live
Pure live ticker for an entire league.	/v1/ws/live + filter client-side.

For dashboards displaying < 20 matches, opening one WS per match is simpler than filtering the firehose.