> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportrix.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Sportrix Data Quickstart: First REST Call and WebSocket
> Learn to call the Sportrix Data REST API and subscribe to the live WebSocket stream with step-by-step curl and Python code examples.
This guide walks you from zero to a working integration — a verified REST call against the fixture catalog and a live WebSocket subscription that prints score updates to your terminal. You'll need your API key and about five minutes.
All endpoints except `GET /health` require your API key in the `X-API-Key` request header.
API keys are issued to your account (a **client**) by the Sportrix Data team. Contact [support](mailto:support@sportrixdata.com) to request a key for your account.
Your key will look like this:
```
sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdef
```
Keys always begin with `sk_`. Keep your key secret — do not commit it to source control or expose it in client-side code.
Call `GET /sports` to confirm your key is valid and see which sports are enabled on your account:
```bash theme={null}
curl https://api.sportrixdata.com/api/sports \
-H "X-API-Key: sk_your_api_key_here"
```
A successful response returns an array of your enabled sports:
```json theme={null}
[
{ "id": 1, "name": "Soccer" }
]
```
Note the `id` of the sport you want to work with — you'll use it in the next step.
If you receive a `401 Unauthorized` response, double-check that you copied the key correctly and that it hasn't been disabled or expired.
Call `GET /leagues` with your sport id to browse the leagues available on your account:
```bash theme={null}
curl "https://api.sportrixdata.com/api/leagues?sport=1" \
-H "X-API-Key: sk_your_api_key_here"
```
Results come back in a pagination envelope:
```json theme={null}
{
"items": [
{ "id": 172, "name": "USA USL W-League Women" }
],
"total": 1,
"limit": 100,
"offset": 0,
"count": 1,
"page": 1,
"total_pages": 1,
"has_more": false
}
```
Note the `id` of the league you want to explore.
Call `GET /matches` with the league id from the previous step to see matches. Use `status=STARTED` to focus on in-play matches:
```bash All matches theme={null}
curl "https://api.sportrixdata.com/api/matches?league=172" \
-H "X-API-Key: sk_your_api_key_here"
```
```bash In-play only theme={null}
curl "https://api.sportrixdata.com/api/matches?league=172&status=STARTED" \
-H "X-API-Key: sk_your_api_key_here"
```
Each item in the response is a match object:
```json theme={null}
{
"items": [
{
"id": 41301,
"home_team": "Salmon Bay FC (W)",
"away_team": "West Seattle Rhodies FC (W)",
"start_time": "2026-06-18T02:00:00Z",
"status": "NOT_STARTED"
}
],
"total": 1,
"limit": 100,
"offset": 0,
"count": 1,
"page": 1,
"total_pages": 1,
"has_more": false
}
```
Note the `id` of a match you want to track — you'll use it in the next steps.
If your key has the `live_scores` or `live_scores_statistics` scope, call `GET /matches/{id}/live` to get the current live state of a match:
```bash theme={null}
curl "https://api.sportrixdata.com/api/matches/41282/live" \
-H "X-API-Key: sk_your_api_key_here"
```
The response is a live snapshot object with the current score, clock, phase, statistics, and event timeline:
```json theme={null}
{
"v": 1,
"sport": "soccer",
"competition": "USA MLS Next Pro League",
"home": "Vancouver Whitecaps II",
"away": "The Town",
"status": "live",
"clock": { "minute": 75, "second": 56, "period": "2H", "running": true, "added": 0 },
"score": { "home": 3, "away": 2 },
"phase": { "label": "Dangerous attack", "team": "away" },
"stats": {
"shots_on_target": { "home": 4, "away": 2 },
"possession": { "home": 56, "away": 44 },
"corners": { "home": 5, "away": 3 }
},
"events": [
{ "minute": "60", "type": "goal", "team": "home", "label": "Goal", "score": "1-0" }
],
"updated_at": "2026-06-18T02:56:50Z"
}
```
This endpoint returns the last-known state even if the match has just ended, so you can safely poll it throughout and after a match.
If your key has the `live_scores_statistics` scope, you can subscribe to real-time push updates instead of polling. Install the `websocket-client` library (`pip install websocket-client`), then run the script below — substituting your key and a live match id:
```python theme={null}
import json, websocket # websocket-client
ws = websocket.create_connection(
"wss://scores.sportrixdata.com/v1/stream?key=sk_your_api_key_here"
)
ws.send(json.dumps({"action": "subscribe", "match_id": 41282}))
while True:
msg = json.loads(ws.recv())
if msg["op"] in ("snapshot", "update"):
d = msg["data"]
if d["sport"] == "cricket": # cricket has its own shape (no clock/phase)
s = d["score"]
print(f'{d["batting"]} {s["runs"]}/{s["wickets"]} ({s["overs"]}) '
f'- {d["last_event"]["label"]}')
else: # soccer
clock = d["clock"]
print(f'{d["home"]} {d["score"]["home"]}-{d["score"]["away"]} {d["away"]} '
f'[{clock["minute"]}:{clock["second"]:02d} {clock["period"]}] {d["phase"]["label"]}')
elif msg["op"] == "error":
print("error:", msg["error"])
```
After subscribing, you'll immediately receive a `snapshot` frame with the full current state, followed by `update` frames whenever the match state changes:
```
Vancouver Whitecaps II 3-2 The Town [75:56 2H] Dangerous attack
Vancouver Whitecaps II 3-3 The Town [77:12 2H] Goal
```
A single connection can subscribe to multiple matches simultaneously — each incoming frame carries the `match_id` so you can route updates correctly.