openapi: 3.0.3
info:
  title: BALLDONTLIE CBA API
  version: 1.0.0
  description: >-
    Chinese Basketball Association teams, players, games, rosters, standings, scoring, and
    statistics. Season values are start years. Date filters use Asia/Shanghai; timestamps are UTC.
    Unavailable values are null.
servers:
  - url: https://api.balldontlie.io/cba/v1
security:
  - ApiKey: []
paths:
  /teams:
    get:
      summary: List teams
      operationId: listTeams
      description: 'Teams in the Chinese Basketball Association. Minimum tier: Free.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: search
          in: query
          required: false
          description: Case-insensitive substring match on name.
          schema:
            type: string
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Teams'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 1
                    name: 北京控股
                meta:
                  next_cursor: 1
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /teams/{id}:
    get:
      summary: Get a team
      operationId: getTeams
      description: 'Minimum tier: Free.'
      parameters:
        - name: id
          in: path
          required: true
          description: Team ID.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Single result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Teams'
              example:
                data:
                  id: 14
                  name: 上海久事
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '404':
          description: Not Found.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /players:
    get:
      summary: List players
      operationId: listPlayers
      description: 'Player profiles. Unavailable profile fields are null. Minimum tier: Free.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: search
          in: query
          required: false
          description: Case-insensitive substring match on name.
          schema:
            type: string
        - name: player_ids[]
          in: query
          required: false
          description: Filter by player IDs from /players.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Players'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 1
                    name: 白啸桐
                    birth_date: '2007-05-18'
                    height: 186
                    weight: 83
                    nationality: 中国
                    position: 控球后卫
                meta:
                  next_cursor: 1
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /players/{id}:
    get:
      summary: Get a player
      operationId: getPlayers
      description: 'Minimum tier: Free.'
      parameters:
        - name: id
          in: path
          required: true
          description: Player ID.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Single result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Players'
              example:
                data:
                  id: 261
                  name: 古德温
                  birth_date: '1995-10-02'
                  height: 183
                  weight: 81
                  nationality: 美国
                  position: 得分后卫/控球后卫
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '404':
          description: Not Found.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /games:
    get:
      summary: List games
      operationId: listGames
      description: >-
        Scheduled and completed games with teams and scores. Game timestamps are UTC; date filters
        use Asia/Shanghai. Minimum tier: Free.
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season_type
          in: query
          required: false
          description: 'Season type: regular, playoffs, preseason, all_star, or relegation.'
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - preseason
              - all_star
              - relegation
        - name: seasons[]
          in: query
          required: false
          description: Season start years, for example 2025 for 2025–26.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: dates[]
          in: query
          required: false
          description: Game dates (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: array
            items:
              type: string
              format: date
          style: form
          explode: true
        - name: start_date
          in: query
          required: false
          description: Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Games'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 17705
                    season: 2025
                    season_type: playoffs
                    datetime: '2026-06-05T11:35:00.000Z'
                    status: final
                    current_period: 4
                    home_team:
                      id: 14
                      name: 上海久事
                    visitor_team:
                      id: 20
                      name: 浙江浙商证券
                    home_team_score: 103
                    visitor_team_score: 82
                meta:
                  next_cursor: 17705
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /games/{id}:
    get:
      summary: Get a game
      operationId: getGames
      description: 'Minimum tier: Free.'
      parameters:
        - name: id
          in: path
          required: true
          description: Game ID.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Single result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Games'
              example:
                data:
                  id: 17705
                  season: 2025
                  season_type: playoffs
                  datetime: '2026-06-05T11:35:00.000Z'
                  status: final
                  current_period: 4
                  home_team:
                    id: 14
                    name: 上海久事
                  visitor_team:
                    id: 20
                    name: 浙江浙商证券
                  home_team_score: 103
                  visitor_team_score: 82
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '404':
          description: Not Found.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /team_rosters:
    get:
      summary: List team rosters
      operationId: listTeamRosters
      description: 'Team rosters by season. A player can appear for more than one team. Minimum tier: ALL-STAR.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids[]
          in: query
          required: false
          description: Filter by player IDs from /players.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season
          in: query
          required: false
          description: Season start year, for example 2025 for 2025–26.
          schema:
            type: integer
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamRosters'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 13765
                    team:
                      id: 14
                      name: 上海久事
                    player:
                      id: 244
                      name: 崔晓龙
                      birth_date: '1999-02-19'
                      height: 193
                      weight: 87
                      nationality: 中国
                      position: 控球后卫/得分后卫
                    season: 2025
                    jersey_number: '5'
                meta:
                  next_cursor: 13765
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /standings:
    get:
      summary: List standings
      operationId: listStandings
      description: 'Team standings by season. Minimum tier: ALL-STAR.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season
          in: query
          required: false
          description: Season start year, for example 2025 for 2025–26.
          schema:
            type: integer
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Standings'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 1509
                    team:
                      id: 14
                      name: 上海久事
                    season: 2025
                    rank: 1
                    games_played: 42
                    wins: 38
                    losses: 4
                    points_for: 4206
                    points_against: 3508
                meta:
                  next_cursor: 1509
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /lineups:
    get:
      summary: List lineups
      operationId: listLineups
      description: >-
        Game participants with jersey numbers and starter status. This is not a complete list of
        inactive players. Minimum tier: ALL-STAR.
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids[]
          in: query
          required: false
          description: Filter by player IDs from /players.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: game_id
          in: query
          required: true
          description: Required game ID from /games.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lineups'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 266511
                    team:
                      id: 14
                      name: 上海久事
                    player:
                      id: 261
                      name: 古德温
                      birth_date: '1995-10-02'
                      height: 183
                      weight: 81
                      nationality: 美国
                      position: 得分后卫/控球后卫
                    game_id: 17705
                    jersey_number: '0'
                    starter: true
                meta:
                  next_cursor: 266511
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /scoring:
    get:
      summary: List scoring
      operationId: listScoring
      description: >-
        Cumulative scores ordered by period and sequence. These are scoring updates, not
        play-by-play events. Corrections can reduce a score. Minimum tier: ALL-STAR.
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: game_id
          in: query
          required: true
          description: Required game ID from /games.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: period
          in: query
          required: false
          description: >-
            Period number. Team statistics accept 0 for full-game totals; scoring starts at 1.
            Maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Scoring'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 493756
                    game_id: 17705
                    period: 1
                    sequence: 1
                    home_team_score: 2
                    visitor_team_score: 0
                meta:
                  next_cursor: 493756
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /player_stats:
    get:
      summary: List player stats
      operationId: listPlayerStats
      description: 'Player box scores by game. Missing statistics are null, not zero. Minimum tier: GOAT.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids[]
          in: query
          required: false
          description: Filter by player IDs from /players.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season_type
          in: query
          required: false
          description: 'Season type: regular, playoffs, preseason, all_star, or relegation.'
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - preseason
              - all_star
              - relegation
        - name: seasons[]
          in: query
          required: false
          description: Season start years, for example 2025 for 2025–26.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: game_ids[]
          in: query
          required: false
          description: Filter by game IDs from /games.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: dates[]
          in: query
          required: false
          description: Game dates (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: array
            items:
              type: string
              format: date
          style: form
          explode: true
        - name: start_date
          in: query
          required: false
          description: Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlayerStats'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 266511
                    team:
                      id: 14
                      name: 上海久事
                    player:
                      id: 261
                      name: 古德温
                      birth_date: '1995-10-02'
                      height: 183
                      weight: 81
                      nationality: 美国
                      position: 得分后卫/控球后卫
                    game_id: 17705
                    pts: 25
                    reb: 4
                    oreb: 0
                    dreb: 4
                    ast: 4
                    stl: 2
                    blk: 1
                    turnover: 4
                    pf: 2
                    fgm: 10
                    fga: 19
                    fg3m: 0
                    fg3a: 5
                    ftm: 5
                    fta: 5
                    seconds: 2134
                    plus_minus: 26
                meta:
                  next_cursor: 266511
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /team_stats:
    get:
      summary: List team stats
      operationId: listTeamStats
      description: 'Team statistics by game and period. Use period=0 for full-game totals. Minimum tier: GOAT.'
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season_type
          in: query
          required: false
          description: 'Season type: regular, playoffs, preseason, all_star, or relegation.'
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - preseason
              - all_star
              - relegation
        - name: period
          in: query
          required: false
          description: >-
            Period number. Team statistics accept 0 for full-game totals; scoring starts at 1.
            Maximum 100.
          schema:
            type: integer
            minimum: 0
            maximum: 100
        - name: seasons[]
          in: query
          required: false
          description: Season start years, for example 2025 for 2025–26.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: game_ids[]
          in: query
          required: false
          description: Filter by game IDs from /games.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: dates[]
          in: query
          required: false
          description: Game dates (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: array
            items:
              type: string
              format: date
          style: form
          explode: true
        - name: start_date
          in: query
          required: false
          description: Inclusive first game date (YYYY-MM-DD) in Asia/Shanghai.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: Inclusive last game date (YYYY-MM-DD) in Asia/Shanghai; must be on or after start_date.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamStats'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 131624
                    team:
                      id: 14
                      name: 上海久事
                    game_id: 17705
                    period: 0
                    pts: 103
                    reb: 45
                    oreb: 16
                    dreb: 29
                    ast: 17
                    stl: 10
                    blk: 4
                    turnover: 10
                    pf: 23
                    fgm: 39
                    fga: 78
                    fg3m: 5
                    fg3a: 21
                    ftm: 20
                    fta: 24
                meta:
                  next_cursor: 131624
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
  /season_averages:
    get:
      summary: List season averages
      operationId: listSeasonAverages
      description: >-
        Player averages by team, season, and season type. A player who changes teams can have
        multiple rows. Missing averages are null. Minimum tier: GOAT.
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor from meta.next_cursor. Omit for the first page.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: per_page
          in: query
          required: false
          description: Results per page. Default 25; maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: team_ids[]
          in: query
          required: false
          description: Filter by team IDs from /teams.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids[]
          in: query
          required: false
          description: Filter by player IDs from /players.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: season
          in: query
          required: false
          description: Season start year, for example 2025 for 2025–26.
          schema:
            type: integer
        - name: season_type
          in: query
          required: false
          description: 'Season type: regular, playoffs, preseason, all_star, or relegation.'
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - preseason
              - all_star
              - relegation
      responses:
        '200':
          description: Paginated results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SeasonAverages'
                  meta:
                    type: object
                    required:
                      - per_page
                    properties:
                      per_page:
                        type: integer
                      next_cursor:
                        type: integer
                        description: Omitted at the end.
                      prev_cursor:
                        type: integer
                        description: Echoes the supplied cursor when present.
              example:
                data:
                  - id: 21674
                    team:
                      id: 14
                      name: 上海久事
                    player:
                      id: 261
                      name: 古德温
                      birth_date: '1995-10-02'
                      height: 183
                      weight: 81
                      nationality: 美国
                      position: 得分后卫/控球后卫
                    season: 2025
                    season_type: regular
                    games_played: 42
                    pts: 15.9
                    reb: 3.8
                    oreb: 0.7
                    dreb: 3.1
                    ast: 7.1
                    stl: 0.8
                    blk: 0.1
                    turnover: 2.1
                    pf: 1.5
                    fgm: 5.9
                    fga: 10.9
                    fg3m: 1.4
                    fg3a: 4
                    ftm: 2.8
                    fta: 4
                meta:
                  next_cursor: 21674
                  per_page: 1
        '400':
          description: Invalid parameters.
        '401':
          description: 'Unauthorized: API key or tier access.'
        '429':
          description: Rate limit exceeded.
        '500':
          description: Server error.
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    Teams:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: ID.
        name:
          type: string
          description: Name.
    Players:
      type: object
      required:
        - id
        - name
        - birth_date
        - height
        - weight
        - nationality
        - position
      properties:
        id:
          type: integer
          description: ID.
        name:
          type: string
          description: Name.
        birth_date:
          type: string
          description: Date of birth (YYYY-MM-DD).
          nullable: true
          format: date
        height:
          type: number
          description: Height.
          nullable: true
        weight:
          type: number
          description: Weight.
          nullable: true
        nationality:
          type: string
          description: Nationality.
          nullable: true
        position:
          type: string
          description: Playing position.
          nullable: true
    Games:
      type: object
      required:
        - id
        - season
        - season_type
        - datetime
        - status
        - current_period
        - home_team
        - visitor_team
        - home_team_score
        - visitor_team_score
      properties:
        id:
          type: integer
          description: ID.
        season:
          type: integer
          description: Season start year.
        season_type:
          type: string
          description: Season type.
          nullable: true
          enum:
            - regular
            - playoffs
            - preseason
            - all_star
            - relegation
            - null
        datetime:
          type: string
          description: Game timestamp in UTC.
          format: date-time
        status:
          type: string
          description: Game status.
        current_period:
          type: integer
          description: Current period number.
          nullable: true
        home_team:
          type: object
          description: Home team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        visitor_team:
          type: object
          description: Visiting team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        home_team_score:
          type: integer
          description: Home team score.
          nullable: true
        visitor_team_score:
          type: integer
          description: Visiting team score.
          nullable: true
    TeamRosters:
      type: object
      required:
        - id
        - team
        - player
        - season
        - jersey_number
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        player:
          type: object
          description: Player.
          required:
            - id
            - name
            - birth_date
            - height
            - weight
            - nationality
            - position
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
            birth_date:
              type: string
              description: Date of birth (YYYY-MM-DD).
              nullable: true
              format: date
            height:
              type: number
              description: Height.
              nullable: true
            weight:
              type: number
              description: Weight.
              nullable: true
            nationality:
              type: string
              description: Nationality.
              nullable: true
            position:
              type: string
              description: Playing position.
              nullable: true
        season:
          type: integer
          description: Season start year.
        jersey_number:
          type: string
          description: Jersey number.
          nullable: true
    Standings:
      type: object
      required:
        - id
        - team
        - season
        - rank
        - games_played
        - wins
        - losses
        - points_for
        - points_against
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        season:
          type: integer
          description: Season start year.
        rank:
          type: integer
          description: Standing rank.
        games_played:
          type: integer
          description: Games played.
        wins:
          type: integer
          description: Wins.
        losses:
          type: integer
          description: Losses.
        points_for:
          type: integer
          description: Points scored.
          nullable: true
        points_against:
          type: integer
          description: Points conceded.
          nullable: true
    Lineups:
      type: object
      required:
        - id
        - team
        - player
        - game_id
        - jersey_number
        - starter
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        player:
          type: object
          description: Player.
          required:
            - id
            - name
            - birth_date
            - height
            - weight
            - nationality
            - position
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
            birth_date:
              type: string
              description: Date of birth (YYYY-MM-DD).
              nullable: true
              format: date
            height:
              type: number
              description: Height.
              nullable: true
            weight:
              type: number
              description: Weight.
              nullable: true
            nationality:
              type: string
              description: Nationality.
              nullable: true
            position:
              type: string
              description: Playing position.
              nullable: true
        game_id:
          type: integer
          description: Game ID from /games.
        jersey_number:
          type: string
          description: Jersey number.
          nullable: true
        starter:
          type: boolean
          description: Whether the player started the game.
          nullable: true
    Scoring:
      type: object
      required:
        - id
        - game_id
        - period
        - sequence
        - home_team_score
        - visitor_team_score
      properties:
        id:
          type: integer
          description: ID.
        game_id:
          type: integer
          description: Game ID from /games.
        period:
          type: integer
          description: Period number; 0 denotes full-game totals in team statistics.
        sequence:
          type: integer
          description: Order within the period.
        home_team_score:
          type: integer
          description: Home team score.
        visitor_team_score:
          type: integer
          description: Visiting team score.
    PlayerStats:
      type: object
      required:
        - id
        - team
        - player
        - game_id
        - pts
        - reb
        - oreb
        - dreb
        - ast
        - stl
        - blk
        - turnover
        - pf
        - fgm
        - fga
        - fg3m
        - fg3a
        - ftm
        - fta
        - seconds
        - plus_minus
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        player:
          type: object
          description: Player.
          required:
            - id
            - name
            - birth_date
            - height
            - weight
            - nationality
            - position
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
            birth_date:
              type: string
              description: Date of birth (YYYY-MM-DD).
              nullable: true
              format: date
            height:
              type: number
              description: Height.
              nullable: true
            weight:
              type: number
              description: Weight.
              nullable: true
            nationality:
              type: string
              description: Nationality.
              nullable: true
            position:
              type: string
              description: Playing position.
              nullable: true
        game_id:
          type: integer
          description: Game ID from /games.
        pts:
          type: number
          description: Points
          nullable: true
        reb:
          type: number
          description: Total rebounds
          nullable: true
        oreb:
          type: number
          description: Offensive rebounds
          nullable: true
        dreb:
          type: number
          description: Defensive rebounds
          nullable: true
        ast:
          type: number
          description: Assists
          nullable: true
        stl:
          type: number
          description: Steals
          nullable: true
        blk:
          type: number
          description: Blocks
          nullable: true
        turnover:
          type: number
          description: Turnovers
          nullable: true
        pf:
          type: number
          description: Personal fouls
          nullable: true
        fgm:
          type: number
          description: Field goals made
          nullable: true
        fga:
          type: number
          description: Field goals attempted
          nullable: true
        fg3m:
          type: number
          description: Three-pointers made
          nullable: true
        fg3a:
          type: number
          description: Three-pointers attempted
          nullable: true
        ftm:
          type: number
          description: Free throws made
          nullable: true
        fta:
          type: number
          description: Free throws attempted
          nullable: true
        seconds:
          type: number
          description: Playing time in seconds
          nullable: true
        plus_minus:
          type: number
          description: Plus/minus
          nullable: true
    TeamStats:
      type: object
      required:
        - id
        - team
        - game_id
        - period
        - pts
        - reb
        - oreb
        - dreb
        - ast
        - stl
        - blk
        - turnover
        - pf
        - fgm
        - fga
        - fg3m
        - fg3a
        - ftm
        - fta
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        game_id:
          type: integer
          description: Game ID from /games.
        period:
          type: integer
          description: Period number; 0 denotes full-game totals in team statistics.
        pts:
          type: number
          description: Points
          nullable: true
        reb:
          type: number
          description: Total rebounds
          nullable: true
        oreb:
          type: number
          description: Offensive rebounds
          nullable: true
        dreb:
          type: number
          description: Defensive rebounds
          nullable: true
        ast:
          type: number
          description: Assists
          nullable: true
        stl:
          type: number
          description: Steals
          nullable: true
        blk:
          type: number
          description: Blocks
          nullable: true
        turnover:
          type: number
          description: Turnovers
          nullable: true
        pf:
          type: number
          description: Personal fouls
          nullable: true
        fgm:
          type: number
          description: Field goals made
          nullable: true
        fga:
          type: number
          description: Field goals attempted
          nullable: true
        fg3m:
          type: number
          description: Three-pointers made
          nullable: true
        fg3a:
          type: number
          description: Three-pointers attempted
          nullable: true
        ftm:
          type: number
          description: Free throws made
          nullable: true
        fta:
          type: number
          description: Free throws attempted
          nullable: true
    SeasonAverages:
      type: object
      required:
        - id
        - team
        - player
        - season
        - season_type
        - games_played
        - pts
        - reb
        - oreb
        - dreb
        - ast
        - stl
        - blk
        - turnover
        - pf
        - fgm
        - fga
        - fg3m
        - fg3a
        - ftm
        - fta
      properties:
        id:
          type: integer
          description: ID.
        team:
          type: object
          description: Team.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
        player:
          type: object
          description: Player.
          required:
            - id
            - name
            - birth_date
            - height
            - weight
            - nationality
            - position
          properties:
            id:
              type: integer
              description: ID.
            name:
              type: string
              description: Name.
            birth_date:
              type: string
              description: Date of birth (YYYY-MM-DD).
              nullable: true
              format: date
            height:
              type: number
              description: Height.
              nullable: true
            weight:
              type: number
              description: Weight.
              nullable: true
            nationality:
              type: string
              description: Nationality.
              nullable: true
            position:
              type: string
              description: Playing position.
              nullable: true
        season:
          type: integer
          description: Season start year.
        season_type:
          type: string
          description: Season type.
          nullable: true
          enum:
            - regular
            - playoffs
            - preseason
            - all_star
            - relegation
            - null
        games_played:
          type: number
          description: Games played.
          nullable: true
        pts:
          type: number
          description: Points
          nullable: true
        reb:
          type: number
          description: Total rebounds
          nullable: true
        oreb:
          type: number
          description: Offensive rebounds
          nullable: true
        dreb:
          type: number
          description: Defensive rebounds
          nullable: true
        ast:
          type: number
          description: Assists
          nullable: true
        stl:
          type: number
          description: Steals
          nullable: true
        blk:
          type: number
          description: Blocks
          nullable: true
        turnover:
          type: number
          description: Turnovers
          nullable: true
        pf:
          type: number
          description: Personal fouls
          nullable: true
        fgm:
          type: number
          description: Field goals made
          nullable: true
        fga:
          type: number
          description: Field goals attempted
          nullable: true
        fg3m:
          type: number
          description: Three-pointers made
          nullable: true
        fg3a:
          type: number
          description: Three-pointers attempted
          nullable: true
        ftm:
          type: number
          description: Free throws made
          nullable: true
        fta:
          type: number
          description: Free throws attempted
          nullable: true