SportriX Quickstart: First REST Call and WebSocket

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.

Get your API key

API keys are issued to your account (a client) by the SportriX team. Contact support 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.

Verify your key works

Call GET /sports to confirm your key is valid and see which sports are enabled on your account:

curl https://api.sportrix.ai/api/sports \
  -H "X-API-Key: sk_your_api_key_here"

A successful response returns an array of your enabled sports:

[
  { "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.

Find a league

Call GET /leagues with your sport id to browse the leagues available on your account:

curl "https://api.sportrix.ai/api/leagues?sport=1" \
  -H "X-API-Key: sk_your_api_key_here"

Results come back in a pagination envelope:

{
  "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.

List matches in a league

Call GET /matches with the league id from the previous step to see matches. Use status=STARTED to focus on in-play matches:

curl "https://api.sportrix.ai/api/matches?league=172" \
  -H "X-API-Key: sk_your_api_key_here"

curl "https://api.sportrix.ai/api/matches?league=172&status=STARTED" \
  -H "X-API-Key: sk_your_api_key_here"

Each item in the response is a match object:

{
  "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.

Fetch a live score snapshot

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:

curl "https://api.sportrix.ai/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:

{
  "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.

Stream live updates over WebSocket

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:

import json, websocket  # websocket-client

ws = websocket.create_connection(
    "wss://scores.sportrix.ai/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.

Get Started

Core Concepts

Guides

SportriX Quickstart: First REST Call and WebSocket