Games

Games represent scheduled matchups with scores and sport-specific stats. The Staty API supports 6 sport types, each with a distinct schema.

Endpoint: /api/v1/games Required scope: read:games (read) / admin (write)

Get teams and rosters in one request by populating both at the same time: ?include=homeTeam.players,awayTeam.players,organization,league. See Query Parameter: ?include= for the full grammar.

Endpoints

Method	Path	Auth	Description
GET	`/api/v1/games?division=:id`	Recommended	List games for a division
GET	`/api/v1/games/:id`	Recommended	Get a single game
GET	`/api/v1/games?division=:id&include=homeTeam.players,awayTeam.players`	Recommended	Games with team rosters
POST	`/api/v1/games`	Required	Create a game
PUT	`/api/v1/games/:id`	Required	Update game scores or details

Allowed ?include= roots: homeTeam, awayTeam, organization, league, division.

Filtering & pagination on GET /api/v1/games: ?division=, ?league=, and ?organization= filter the list; results are newest-first. ?limit= defaults to 500 (max 1000) and ?page= (1-based) pages through larger sets. Always scope by one of the filters rather than paging the whole collection.

Common Fields (All Sports)

Field	Type	Default	Description
`_id`	ObjectId	—	Unique identifier
`date`	date	now	Game date
`time`	string	—	Game time string
`duration`	number	`60`	Duration in minutes
`isBye`	boolean	—	Whether this is a bye game
`organization`	string	—	Owning organization ID
`league`	string	—	Parent league ID
`division`	string	—	Parent division ID
`location`	string	—	Location text
`locationModel`	ObjectId	—	Venue (ref: Location)
`gameLabel`	string	—	Custom label (e.g. “Game 1”, “Semifinal A”)
`playoffRound`	string	—	`quarterfinal`, `consolation_semifinal`, `semifinal`, `championship`, `third_place`, `fifth_place`, `seventh_place`, `consolation`
`isCancelled`	boolean	`false`	Whether game is cancelled
`isHidden`	boolean	`false`	Whether game is hidden from public views
`globalDate`	string	—	Timezone-agnostic date string
`timeSlot`	ObjectId	—	Scheduled time slot (ref: TimeSlot)
`created`	date	—	Creation timestamp
`updated`	date	—	Last update timestamp

Basketball (shared team-game schema)

sport: "basketball". This schema also backs volleyball and soccer games.

Field	Type	Description
`homeTeam`	ObjectId	Home team (ref: DivisionTeam)
`awayTeam`	ObjectId	Away team (ref: DivisionTeam)
`homeTeamPlaceholder`	string	Placeholder name (e.g. “Winner Game 3”)
`awayTeamPlaceholder`	string	Placeholder name
`homeScore`	number	Home team score. For volleyball this stores sets won
`awayScore`	number	Away team score. For volleyball this stores sets won
`setScores`	array	Volleyball only: per-set points, `[{ "home": 25, "away": 20 }, ...]` (up to 5 sets). When present, `homeScore`/`awayScore` are derived as sets won

Baseball

sport: "baseball"

Field	Type	Description
`homeTeam`	ObjectId	Home team (ref: DivisionTeam)
`awayTeam`	ObjectId	Away team (ref: DivisionTeam)
`homeScore`	number	Home team score
`awayScore`	number	Away team score

Judo

sport: "judo"

Field	Type	Description
`winner`	ObjectId	Winning competitor (ref: Player)
`gender`	string	`male` or `female`. Default: `"male"`
`round`	string	Match round

Golf

sport: "golf"

Field	Type	Description
`format`	string	`stroke`, `match`, or `stableford`. Default: `"stroke"`

Racket (Tennis, Badminton, etc.)

sport: "racket"

Field	Type	Description
`format`	string	`best-of-1`, `best-of-3`, `best-of-5`. Default: `"best-of-3"`

Track & Field

sport: "track"

Field	Type	Description
`eventName`	string	Event name (e.g. “100m Sprint”, “Long Jump”)
`resultType`	string	`time`, `distance`, or `points`
`gender`	string	`male`, `female`, or `mixed`. Default: `"mixed"`
`isRelay`	boolean	Whether this is a relay event. Default: `false`
`participants`	string[]	Participant player IDs

Example: List Games with Players


curl "https://api.staty.io/api/v1/games?division=div_def456&include=homeTeam.players,awayTeam.players" \
  -H "Authorization: Bearer sk_live_..."

Response:


{
  "success": true,
  "data": [
    {
      "_id": "game_abc",
      "sport": "basketball",
      "date": "2026-04-10T19:00:00.000Z",
      "duration": 60,
      "homeTeam": {
        "_id": "divteam_1",
        "name": "Thunder",
        "players": [
          { "_id": "player_1", "name": "Alex Johnson", "number": "7" }
        ]
      },
      "awayTeam": {
        "_id": "divteam_2",
        "name": "Lightning",
        "players": [
          { "_id": "player_2", "name": "Sam Lee", "number": "11" }
        ]
      },
      "homeScore": null,
      "awayScore": null
    }
  ],
  "count": 1
}