Upcoming games

Endpoint

GET /api/upcoming

Top-level, like the sessions catalog. The rows are scheduled games, not sessions — access can be granted on a game before any feed exists for it, and this endpoint is where those grants surface: your schedule of covered games, soonest first. There is nothing to subscribe to yet; when coverage goes live, the session appears in GET /api/sessions carrying the same gameId, and every feed URL comes from that session row. A game leaves this list when its scheduled window has fully passed, whether or not a session ever covered it.

Authentication

Same as the sessions catalog: a valid ss_ API key or JWT as a Bearer token or ?token=, no anonymous tier. The list is exactly the games your account was granted — there is no public slice here.

Error responses

Status	Condition
`401`	Missing or invalid token

Response

{
  "games": [
    {
      "gameId": "5f0c9d0e-3c14-4c6e-9d38-7a4f0a1b2c3d",
      "league": "wnba",
      "sport": "basketball",
      "matchup": { "a": "Dallas Wings", "b": "Connecticut Sun" },
      "summary": "Connecticut Sun @ Dallas Wings",
      "scheduledStart": "2026-08-02T23:00:00+00:00"
    }
  ]
}

Field	Type	Description
`gameId`	string	The scheduled game’s id. The join key against the sessions catalog: sessions covering this game carry the same value as their `gameId`, so replace this row with the session row(s) once they appear
`league`	string	League slug — same vocabulary as the sessions catalog
`sport`	string	Which event vocabulary and state shape the eventual feed will speak — same values as the catalog’s `sport`
`matchup`	object	The side display names `{ a, b }` (home, away). Either side is `null` for a manually-entered game without team fields — fall back to `summary`
`summary`	string \| null	A human-readable game label, when one exists
`scheduledStart`	string	ISO-8601 scheduled start time. A promise from the schedule, not a session stamp — the session’s own `startedAt` is when coverage actually began

Ordering is soonest first (scheduledStart ascending).

Polling pattern

Poll this beside GET /api/sessions?status=open and key both by gameId: a game in this list with no matching open session is scheduled; once an open session shares its gameId, that session row is the live one (subscribe with its sessionId), and this list drops the game shortly after its window passes.

Getting Started

Core Concepts

API Reference

Sports

Reference

Endpoint

Authentication

Error responses

Response

Polling pattern

​Endpoint

​Authentication

​Error responses

​Response

​Polling pattern

Endpoint

Authentication

Error responses

Response

Polling pattern