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.

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`, `semifinal`, `championship`, `third_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

sport: "basketball"

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
`awayScore`	number	Away team score

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
`innings`	number	Number of innings played

Judo

sport: "judo"

Field	Type	Description
`competitorA`	ObjectId	Competitor A (ref: Player)
`competitorB`	ObjectId	Competitor B (ref: Player)
`winner`	ObjectId	Winning competitor (ref: Player)
`method`	string	Win method: `ippon`, `waza-ari`, `hansoku-make`, `decision`
`durationSeconds`	number	Match duration in seconds
`weightClass`	string	Weight class
`gender`	string	`male` or `female`. Default: `"male"`
`round`	string	Match round

Golf

sport: "golf"

Field	Type	Description
`courseName`	string	Golf course name
`holes`	number	Number of holes. Default: `18`
`format`	string	`stroke`, `match`, or `stableford`. Default: `"stroke"`

Racket (Tennis, Badminton, etc.)

sport: "racket"

Field	Type	Description
`playerA`	string[]	Player A IDs (1 for singles, 2 for doubles)
`playerB`	string[]	Player B IDs
`teamA`	ObjectId	Team A (ref: DivisionTeam)
`teamB`	ObjectId	Team B (ref: DivisionTeam)
`winner`	ObjectId	Winning player (ref: Player)
`format`	string	`best-of-1`, `best-of-3`, `best-of-5`. Default: `"best-of-3"`
`isDoubles`	boolean	Doubles match. Default: `false`
`sets`	Set[]	Per-set scores with optional tiebreak

Set Object


{
  "setNumber": 1,
  "playerAScore": 6,
  "playerBScore": 4,
  "tiebreak": {
    "enabled": false
  }
}

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`
`previewStats`	boolean	Show preview stats. Default: `true`
`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
}