Skip to main content

Documentation Index

Fetch the complete documentation index at: https://285e39fd5e337e58f16290.sightscreen.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint reference

MethodRouteAuthPurpose
GET/matchesUserList matches with filters
GET/matches/liveUserAll currently live matches
POST/matches/:matchId/activity-tokenUserRegister/rotate LA update token
POST/matches/:matchId/activity-dismissedUserUser dismissed a Live Activity
POST/user/follow/matchUserFollow a match
PATCH/user/follow/match/:id/teamUserChange supported team
DELETE/user/follow/match/:idUserUnfollow a match
GET/admin/sportmonks/fixturesAdminFetch fixtures from SportMonks
POST/admin/cache/clearAdminClear cached match data
GET/admin/cache/statsAdminView cache statistics

​
List matches

​
GET /matches User

List matches with optional filters. Returns paginated results.
​
league
string
Filter by league ID.
​
status
string
Filter by match status. Values: upcoming, live, completed.
​
from
string
ISO 8601 date string. Only return matches starting after this date.
​
to
string
ISO 8601 date string. Only return matches starting before this date.
GET /matches?league=bbl&status=live&from=2026-01-01&to=2026-03-31

​
GET /matches/live User

Returns all currently live matches across all leagues. No query parameters. 
{
  "matches": [
    {
      "id": "match-001",
      "status": "live",
      "league": "bbl",
      "score": { ... }
    }
  ]
}

​
Live Activity management

These endpoints manage the Live Activity lifecycle for a match on the user’s device.

​
POST /matches/:matchId/activity-token User

Register or rotate a Live Activity update token for a specific match. The iOS app calls this after starting a Live Activity to give the backend the token needed to push updates.
​
matchId
string
required
The match ID this token is associated with.
​
activityToken
string
required
The Live Activity push token from ActivityKit.
{
  "activityToken": "d8a3f1b2c4e5..."
}
Tokens rotate when iOS restarts a Live Activity. The app should call this endpoint each time it receives a new token from ActivityKit.

​
POST /matches/:matchId/activity-dismissed User

Called when the user dismisses a Live Activity on their device. Triggers two actions:
  1. Unfollows the match for this user (equivalent to DELETE /user/follow/match/:id).
  2. Ends all Live Activity records for this user on the match.
​
matchId
string
required
The match whose Live Activity was dismissed.
POST /matches/match-001/activity-dismissed
The dismissal delay is controlled by LA_DISMISSAL_DELAY_MINUTES. The backend waits this period before actually ending the LA, in case the user re-opens the app.

​
Match following

These endpoints manage which matches a user follows. Following a match enables Live Activity updates and score tracking.
See the Match following business flow for the full end-to-end journey.

​
POST /user/follow/match User

Follow a match. If the match is currently live, the backend also:
  1. Creates pending Live Activity records for all of the user’s registered devices.
  2. Sends a push-to-start token via APNs to boot the Live Activity on each device.
​
matchId
string
required
The match to follow.
​
teamId
string
Optional. The team the user supports in this match. Used to personalize the Live Activity display.
{
  "matchId": "match-001",
  "teamId": "team-1"
}
liveActivityCreated is true when the match is live and LA records were created. It is false for upcoming matches — the MatchOrchestrator will create LA records when the match goes live.

​
PATCH /user/follow/match/:id/team User

Change the supported team for a match the user is already following.
​
id
string
required
The followed match ID.
​
teamId
string
required
The new team to support.

​
DELETE /user/follow/match/:id User

Unfollow a match. In addition to removing the follow record, this endpoint ends all active Live Activities for this user on the match by sending end events via APNs.
​
id
string
required
The followed match ID.
{
  "ok": true,
  "liveActivitiesEnded": 2
}

​
Admin match data

​
GET /admin/sportmonks/fixtures Admin

Fetch fixtures directly from the SportMonks API. Useful for debugging data discrepancies.

​
POST /admin/cache/clear Admin

Clear cached live match data. Forces the next poll cycle to fetch fresh data from SportMonks.
​
matchId
string
Clear cache for a specific match. Omit to clear all cached data.

​
GET /admin/cache/stats Admin

View cache hit/miss statistics and memory usage.