Matches

Endpoint reference

Method	Route	Auth	Purpose
`GET`	`/matches`	User	List matches with filters
`GET`	`/matches/live`	User	All currently live matches
`POST`	`/matches/:matchId/activity-token`	User	Register/rotate LA update token
`POST`	`/matches/:matchId/activity-dismissed`	User	User dismissed a Live Activity
`POST`	`/user/follow/match`	User	Follow a match
`PATCH`	`/user/follow/match/:id/team`	User	Change supported team
`DELETE`	`/user/follow/match/:id`	User	Unfollow a match
`GET`	`/admin/sportmonks/fixtures`	Admin	Fetch fixtures from SportMonks
`POST`	`/admin/cache/clear`	Admin	Clear cached match data
`GET`	`/admin/cache/stats`	Admin	View cache statistics

List matches

GET /matches `User`

List matches with optional filters. Returns paginated results.

string

Filter by league ID.

string

Filter by match status. Values: upcoming, live, completed.

string

ISO 8601 date string. Only return matches starting after this date.

string

ISO 8601 date string. Only return matches starting before this date.

Request
Response

GET /matches?league=bbl&status=live&from=2026-01-01&to=2026-03-31

{
  "matches": [
    {
      "id": "match-001",
      "league": "bbl",
      "status": "live",
      "teamA": { "id": "team-1", "name": "Sydney Sixers" },
      "teamB": { "id": "team-2", "name": "Melbourne Stars" },
      "startTime": "2026-01-15T18:00:00Z"
    }
  ]
}

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.

string

required

The match ID this token is associated with.

string

required

The Live Activity push token from ActivityKit.

Request
Response (200)

{
  "activityToken": "d8a3f1b2c4e5..."
}

{
  "ok": true
}

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:

Unfollows the match for this user (equivalent to DELETE /user/follow/match/:id).
Ends all Live Activity records for this user on the match.

string

required

The match whose Live Activity was dismissed.

Request
Response (200)

POST /matches/match-001/activity-dismissed

{
  "ok": true
}

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:

Creates pending Live Activity records for all of the user’s registered devices.
Sends a push-to-start token via APNs to boot the Live Activity on each device.

string

required

The match to follow.

string

Optional. The team the user supports in this match. Used to personalize the Live Activity display.

Request
Response (201)

{
  "matchId": "match-001",
  "teamId": "team-1"
}

{
  "followId": "follow-abc123",
  "matchId": "match-001",
  "teamId": "team-1",
  "liveActivityCreated": true
}

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.

string

required

The followed match ID.

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.

string

required

The followed match ID.

Response (200)

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

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.

Overview

Endpoints

Endpoint reference

List matches

GET /matches `User`

GET /matches/live `User`

Live Activity management

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

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

Match following

POST /user/follow/match `User`

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

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

Admin match data

GET /admin/sportmonks/fixtures `Admin`

POST /admin/cache/clear `Admin`

GET /admin/cache/stats `Admin`

​Endpoint reference

​List matches

​GET /matches User

​GET /matches/live User

​Live Activity management

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

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

​Match following

​POST /user/follow/match User

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

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

​Admin match data

​GET /admin/sportmonks/fixtures Admin

​POST /admin/cache/clear Admin

​GET /admin/cache/stats Admin

Endpoint reference

List matches

GET /matches `User`

GET /matches/live `User`

Live Activity management

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

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

Match following

POST /user/follow/match `User`

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

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

Admin match data

GET /admin/sportmonks/fixtures `Admin`

POST /admin/cache/clear `Admin`

GET /admin/cache/stats `Admin`