openapi: 3.1.0
info:
  title: BALLDONTLIE - NBA API
  version: 1.0.0
  description: NBA endpoints for the BallDontLie API.
servers:
  - url: https://api.balldontlie.io
    description: Production server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
    NBAAdvancedStatsV2:
      type: object
      description: Comprehensive NBA advanced stats including tracking data, hustle stats, and defensive metrics
      properties:
        id:
          type: integer
        period:
          type: integer
          description: Game period (0 for full game)
        player:
          $ref: "#/components/schemas/NBAPlayer"
        team:
          $ref: "#/components/schemas/NBATeam"
        game:
          $ref: "#/components/schemas/NBAGame"
        pie:
          type: number
          nullable: true
          description: Player Impact Estimate
        assist_percentage:
          type: number
          nullable: true
        assist_ratio:
          type: number
          nullable: true
        assist_to_turnover:
          type: number
          nullable: true
        defensive_rating:
          type: number
          nullable: true
        defensive_rebound_percentage:
          type: number
          nullable: true
        effective_field_goal_percentage:
          type: number
          nullable: true
        estimated_defensive_rating:
          type: number
          nullable: true
        estimated_net_rating:
          type: number
          nullable: true
        estimated_offensive_rating:
          type: number
          nullable: true
        estimated_pace:
          type: number
          nullable: true
        estimated_usage_percentage:
          type: number
          nullable: true
        net_rating:
          type: number
          nullable: true
        offensive_rating:
          type: number
          nullable: true
        offensive_rebound_percentage:
          type: number
          nullable: true
        pace:
          type: number
          nullable: true
        pace_per_40:
          type: number
          nullable: true
        possessions:
          type: number
          nullable: true
        rebound_percentage:
          type: number
          nullable: true
        true_shooting_percentage:
          type: number
          nullable: true
        turnover_ratio:
          type: number
          nullable: true
        usage_percentage:
          type: number
          nullable: true
        blocks_against:
          type: number
          nullable: true
        fouls_drawn:
          type: number
          nullable: true
        points_fast_break:
          type: number
          nullable: true
        points_off_turnovers:
          type: number
          nullable: true
        points_paint:
          type: number
          nullable: true
        points_second_chance:
          type: number
          nullable: true
        opp_points_fast_break:
          type: number
          nullable: true
        opp_points_off_turnovers:
          type: number
          nullable: true
        opp_points_paint:
          type: number
          nullable: true
        opp_points_second_chance:
          type: number
          nullable: true
        pct_assisted_2pt:
          type: number
          nullable: true
        pct_assisted_3pt:
          type: number
          nullable: true
        pct_assisted_fgm:
          type: number
          nullable: true
        pct_fga_2pt:
          type: number
          nullable: true
        pct_fga_3pt:
          type: number
          nullable: true
        pct_pts_2pt:
          type: number
          nullable: true
        pct_pts_3pt:
          type: number
          nullable: true
        pct_pts_fast_break:
          type: number
          nullable: true
        pct_pts_free_throw:
          type: number
          nullable: true
        pct_pts_midrange_2pt:
          type: number
          nullable: true
        pct_pts_off_turnovers:
          type: number
          nullable: true
        pct_pts_paint:
          type: number
          nullable: true
        pct_unassisted_2pt:
          type: number
          nullable: true
        pct_unassisted_3pt:
          type: number
          nullable: true
        pct_unassisted_fgm:
          type: number
          nullable: true
        four_factors_efg_pct:
          type: number
          nullable: true
        free_throw_attempt_rate:
          type: number
          nullable: true
        four_factors_oreb_pct:
          type: number
          nullable: true
        opp_efg_pct:
          type: number
          nullable: true
        opp_free_throw_attempt_rate:
          type: number
          nullable: true
        opp_oreb_pct:
          type: number
          nullable: true
        opp_turnover_pct:
          type: number
          nullable: true
        team_turnover_pct:
          type: number
          nullable: true
        box_outs:
          type: number
          nullable: true
        box_out_player_rebounds:
          type: number
          nullable: true
        box_out_player_team_rebounds:
          type: number
          nullable: true
        defensive_box_outs:
          type: number
          nullable: true
        offensive_box_outs:
          type: number
          nullable: true
        charges_drawn:
          type: number
          nullable: true
        contested_shots:
          type: number
          nullable: true
        contested_shots_2pt:
          type: number
          nullable: true
        contested_shots_3pt:
          type: number
          nullable: true
        deflections:
          type: number
          nullable: true
        loose_balls_recovered_def:
          type: number
          nullable: true
        loose_balls_recovered_off:
          type: number
          nullable: true
        loose_balls_recovered_total:
          type: number
          nullable: true
        screen_assists:
          type: number
          nullable: true
        screen_assist_points:
          type: number
          nullable: true
        matchup_minutes:
          type: string
          nullable: true
        matchup_fg_pct:
          type: number
          nullable: true
        matchup_fga:
          type: number
          nullable: true
        matchup_fgm:
          type: number
          nullable: true
        matchup_3pt_pct:
          type: number
          nullable: true
        matchup_3pa:
          type: number
          nullable: true
        matchup_3pm:
          type: number
          nullable: true
        matchup_assists:
          type: number
          nullable: true
        matchup_turnovers:
          type: number
          nullable: true
        partial_possessions:
          type: number
          nullable: true
        matchup_player_points:
          type: number
          nullable: true
        switches_on:
          type: number
          nullable: true
        speed:
          type: number
          nullable: true
        distance:
          type: number
          nullable: true
        touches:
          type: number
          nullable: true
        passes:
          type: number
          nullable: true
        secondary_assists:
          type: number
          nullable: true
        free_throw_assists:
          type: number
          nullable: true
        contested_fga:
          type: number
          nullable: true
        contested_fgm:
          type: number
          nullable: true
        contested_fg_pct:
          type: number
          nullable: true
        uncontested_fga:
          type: number
          nullable: true
        uncontested_fgm:
          type: number
          nullable: true
        uncontested_fg_pct:
          type: number
          nullable: true
        defended_at_rim_fga:
          type: number
          nullable: true
        defended_at_rim_fgm:
          type: number
          nullable: true
        defended_at_rim_fg_pct:
          type: number
          nullable: true
        rebound_chances_def:
          type: number
          nullable: true
        rebound_chances_off:
          type: number
          nullable: true
        rebound_chances_total:
          type: number
          nullable: true
        pct_blocks:
          type: number
          nullable: true
        pct_blocks_allowed:
          type: number
          nullable: true
        pct_fga:
          type: number
          nullable: true
        pct_fgm:
          type: number
          nullable: true
        pct_fta:
          type: number
          nullable: true
        pct_ftm:
          type: number
          nullable: true
        pct_personal_fouls:
          type: number
          nullable: true
        pct_personal_fouls_drawn:
          type: number
          nullable: true
        pct_points:
          type: number
          nullable: true
        pct_rebounds_def:
          type: number
          nullable: true
        pct_rebounds_off:
          type: number
          nullable: true
        pct_rebounds_total:
          type: number
          nullable: true
        pct_steals:
          type: number
          nullable: true
        pct_3pa:
          type: number
          nullable: true
        pct_3pm:
          type: number
          nullable: true
        pct_turnovers:
          type: number
          nullable: true
    NBABettingOdd:
      type: object
      properties:
        id:
          type: integer
          description: Betting odd ID
        game_id:
          type: integer
          description: Game ID
        vendor:
          type: string
          description: Sportsbook vendor name
        spread_home_value:
          type: string
          nullable: true
          description: Home team spread value
        spread_home_odds:
          type: integer
          nullable: true
          description: Home team spread odds
        spread_away_value:
          type: string
          nullable: true
          description: Away team spread value
        spread_away_odds:
          type: integer
          nullable: true
          description: Away team spread odds
        moneyline_home_odds:
          type: integer
          nullable: true
          description: Home team moneyline odds
        moneyline_away_odds:
          type: integer
          nullable: true
          description: Away team moneyline odds
        total_value:
          type: string
          nullable: true
          description: Total points line value
        total_over_odds:
          type: integer
          nullable: true
          description: Over total odds
        total_under_odds:
          type: integer
          nullable: true
          description: Under total odds
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    NBABoxScore:
      type: object
      properties:
        date:
          type: string
          format: date
        season:
          type: integer
        status:
          type: string
        period:
          type: integer
        time:
          type: string
        postseason:
          type: boolean
        home_team_score:
          type: integer
        visitor_team_score:
          type: integer
        home_team:
          type: object
          properties:
            team:
              $ref: "#/components/schemas/NBATeam"
            players:
              type: array
              items:
                type: object
                properties:
                  min:
                    type: string
                  fgm:
                    type: integer
                  fga:
                    type: integer
                  fg_pct:
                    type: number
                  fg3m:
                    type: integer
                  fg3a:
                    type: integer
                  fg3_pct:
                    type: number
                  ftm:
                    type: integer
                  fta:
                    type: integer
                  ft_pct:
                    type: number
                  oreb:
                    type: integer
                  dreb:
                    type: integer
                  reb:
                    type: integer
                  ast:
                    type: integer
                  stl:
                    type: integer
                  blk:
                    type: integer
                  turnover:
                    type: integer
                  pf:
                    type: integer
                  pts:
                    type: integer
                  plus_minus:
                    type: integer
                    nullable: true
                    description: Plus/minus for the player in this game
                  player:
                    $ref: "#/components/schemas/NBAPlayer"
        visitor_team:
          type: object
          properties:
            team:
              $ref: "#/components/schemas/NBATeam"
            players:
              type: array
              items:
                type: object
                properties:
                  min:
                    type: string
                  fgm:
                    type: integer
                  fga:
                    type: integer
                  fg_pct:
                    type: number
                  fg3m:
                    type: integer
                  fg3a:
                    type: integer
                  fg3_pct:
                    type: number
                  ftm:
                    type: integer
                  fta:
                    type: integer
                  ft_pct:
                    type: number
                  oreb:
                    type: integer
                  dreb:
                    type: integer
                  reb:
                    type: integer
                  ast:
                    type: integer
                  stl:
                    type: integer
                  blk:
                    type: integer
                  turnover:
                    type: integer
                  pf:
                    type: integer
                  pts:
                    type: integer
                  plus_minus:
                    type: integer
                    nullable: true
                    description: Plus/minus for the player in this game
                  player:
                    $ref: "#/components/schemas/NBAPlayer"
    NBAContract:
      type: object
      properties:
        id:
          type: integer
          description: Contract ID
        player_id:
          type: integer
          description: Player ID
        season:
          type: integer
          description: Contract season year
        team_id:
          type: integer
          description: Team ID
        cap_hit:
          type: integer
          nullable: true
          description: Annual salary cap hit in dollars
        total_cash:
          type: integer
          nullable: true
          description: Total cash payment for the season in dollars
        base_salary:
          type: integer
          nullable: true
          description: Base salary in dollars
        rank:
          type: integer
          nullable: true
          description: Salary rank
        player:
          type: object
          description: Player information
          properties:
            id:
              type: integer
            first_name:
              type: string
            last_name:
              type: string
            position:
              type: string
            height:
              type: string
            weight:
              type: string
            jersey_number:
              type: string
            college:
              type: string
            country:
              type: string
            draft_year:
              type: integer
            draft_round:
              type: integer
            draft_number:
              type: integer
            team_id:
              type: integer
        team:
          $ref: "#/components/schemas/NBATeam"
    NBAContractAggregate:
      type: object
      properties:
        id:
          type: integer
          description: Contract aggregate ID
        player_id:
          type: integer
          description: Player ID
        start_year:
          type: integer
          description: First year of contract
        end_year:
          type: integer
          description: Last year of contract
        contract_type:
          type: string
          description: Contract type (e.g., Rookie, Free Agent, Extension)
        contract_status:
          type: string
          nullable: true
          description: Contract status (e.g., CURRENT, UPCOMING EXTENSION)
        contract_years:
          type: integer
          nullable: true
          description: Number of years in contract
        total_value:
          type: integer
          nullable: true
          description: Total contract value in dollars
        average_salary:
          type: integer
          nullable: true
          description: Average annual salary in dollars
        guaranteed_at_signing:
          type: integer
          nullable: true
          description: Guaranteed amount at signing in dollars
        total_guaranteed:
          type: integer
          nullable: true
          description: Total guaranteed amount in dollars
        signed_using:
          type: string
          nullable: true
          description: Exception or method used to sign (e.g., Bird Rights, Cap Space)
        free_agent_year:
          type: integer
          nullable: true
          description: Year player becomes a free agent
        free_agent_status:
          type: string
          nullable: true
          description: Free agent status (e.g., UFA, RFA)
        contract_notes:
          type: object
          nullable: true
          description: Additional contract notes (options, escalators, etc.)
        team_id:
          type: integer
          nullable: true
          description: Team ID that signed the contract
        player:
          type: object
          description: Player information
          properties:
            id:
              type: integer
            first_name:
              type: string
            last_name:
              type: string
            position:
              type: string
            height:
              type: string
            weight:
              type: string
            jersey_number:
              type: string
            college:
              type: string
            country:
              type: string
            draft_year:
              type: integer
            draft_round:
              type: integer
            draft_number:
              type: integer
            team_id:
              type: integer
        team:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/NBATeam"
    NBAGame:
      type: object
      properties:
        id:
          type: integer
        date:
          type: string
          format: date
        season:
          type: integer
        status:
          type: string
          nullable: true
        period:
          type: integer
          nullable: true
        time:
          type: string
          nullable: true
        period_detail:
          type: string
          nullable: true
          description: Detailed period information (e.g., 'Final', '1:00 - 2nd Half')
        datetime:
          type: string
          format: date-time
          nullable: true
        postseason:
          type: boolean
        home_team_score:
          type: integer
        visitor_team_score:
          type: integer
        home_team:
          $ref: "#/components/schemas/NBATeam"
        visitor_team:
          $ref: "#/components/schemas/NBATeam"
        ist_stage:
          type: string
          nullable: true
          description: NBA Cup stage (e.g., 'West Semifinal', 'Championship'). Only populated for NBA Cup games. Only available starting with the 2025 season.
    NBALeader:
      type: object
      properties:
        player:
          $ref: "#/components/schemas/NBAPlayer"
        value:
          type: number
        stat_type:
          type: string
          enum:
            - reb
            - dreb
            - tov
            - ast
            - oreb
            - min
            - pts
            - stl
            - blk
        rank:
          type: integer
        season:
          type: integer
        games_played:
          type: integer
    NBALineup:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the lineup entry
        game_id:
          type: integer
          description: ID of the game this lineup belongs to
        starter:
          type: boolean
          description: Whether the player is a starter (true) or bench player (false)
        position:
          type: string
          description: Position the player is listed at for this game
        player:
          type: object
          description: Player information (slim version with team_id)
          properties:
            id:
              type: integer
            first_name:
              type: string
            last_name:
              type: string
            position:
              type: string
            height:
              type: string
            weight:
              type: string
            jersey_number:
              type: string
            college:
              type: string
            country:
              type: string
            draft_year:
              type: integer
            draft_round:
              type: integer
            draft_number:
              type: integer
            team_id:
              type: integer
              description: ID of the player's current team
        team:
          $ref: "#/components/schemas/NBATeam"
    NBAPlay:
      type: object
      properties:
        game_id:
          type: integer
          description: Game ID
        order:
          type: integer
          description: Play order number (starts at 1 and increments sequentially)
        type:
          type: string
          description: Play type (e.g., "Jump Shot", "Layup", "Dunk")
        text:
          type: string
          description: Play description
        home_score:
          type: integer
          description: Home team score after play
        away_score:
          type: integer
          description: Away team score after play
        period:
          type: integer
          description: Period number (1-4 for regulation, 5+ for overtime)
        period_display:
          type: string
          description: Period display text (e.g., "1st Quarter", "OT1")
        clock:
          type: string
          description: Game clock at time of play
        scoring_play:
          type: boolean
          description: Whether this is a scoring play
        shooting_play:
          type: boolean
          description: Whether this is a shooting play
        score_value:
          type: integer
          description: Points scored on this play
        team:
          $ref: "#/components/schemas/NBATeam"
        coordinate_x:
          type: number
          nullable: true
          description: X coordinate on court (if available)
        coordinate_y:
          type: number
          nullable: true
          description: Y coordinate on court (if available)
        wallclock:
          type: string
          format: date-time
          nullable: true
          description: Real-world timestamp of play
        participants:
          type: array
          items:
            type: integer
          description: Array of player IDs involved in this play
    NBAPlayer:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        position:
          type: string
        height:
          type: string
        weight:
          type: string
        jersey_number:
          type: string
        college:
          type: string
        country:
          type: string
        draft_year:
          type: integer
        draft_round:
          type: integer
        draft_number:
          type: integer
        team:
          $ref: "#/components/schemas/NBATeam"
    NBAPlayerInjury:
      type: object
      properties:
        player:
          $ref: "#/components/schemas/NBAPlayer"
        return_date:
          type: string
        description:
          type: string
        status:
          type: string
    NBAPlayerProp:
      type: object
      description: NBA player prop betting data
      required:
        - id
        - game_id
        - player_id
        - vendor
        - prop_type
        - line_value
        - market
        - updated_at
      properties:
        id:
          type: integer
          description: Unique player prop ID
        game_id:
          type: integer
          description: NBA game ID
        player_id:
          type: integer
          description: NBA player ID
        vendor:
          type: string
          description: Sportsbook vendor name
          enum:
            - draftkings
            - betway
            - betrivers
            - ballybet
        prop_type:
          type: string
          description: Type of player prop
          enum:
            - points
            - rebounds
            - assists
            - threes
            - steals
            - blocks
            - points_1q
            - rebounds_1q
            - assists_1q
            - points_first3min
            - rebounds_first3min
            - assists_first3min
          example: points
        line_value:
          type: string
          description: The line value for the prop
          example: "25.5"
        market:
          oneOf:
            - $ref: "#/components/schemas/NBAPlayerPropMarketOverUnder"
            - $ref: "#/components/schemas/NBAPlayerPropMarketMilestone"
          description: Market information - either over_under or milestone type
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this prop was last updated
    NBAPlayerPropMarketMilestone:
      type: object
      description: Milestone market type for player props
      required:
        - type
        - odds
      properties:
        type:
          type: string
          enum:
            - milestone
          description: Market type identifier
        odds:
          type: integer
          description: American odds for milestone bet
    NBAPlayerPropMarketOverUnder:
      type: object
      description: Over/under market type for player props
      required:
        - type
        - over_odds
        - under_odds
      properties:
        type:
          type: string
          enum:
            - over_under
          description: Market type identifier
        over_odds:
          type: integer
          description: American odds for over bet
        under_odds:
          type: integer
          description: American odds for under bet
    NBASeasonAverageV2:
      type: object
      properties:
        player_id:
          type: integer
        season:
          type: integer
        season_type:
          type: string
        stats:
          type: object
          additionalProperties: true
    NBASeasonAverages:
      type: object
      properties:
        games_played:
          type: integer
        pts:
          type: number
        ast:
          type: number
        reb:
          type: number
        stl:
          type: number
        blk:
          type: number
        turnover:
          type: number
        min:
          type: string
        fgm:
          type: number
        fga:
          type: number
        fg_pct:
          type: number
        fg3m:
          type: number
        fg3a:
          type: number
        fg3_pct:
          type: number
        ftm:
          type: number
        fta:
          type: number
        ft_pct:
          type: number
        oreb:
          type: number
        dreb:
          type: number
        player_id:
          type: integer
        season:
          type: integer
    NBAStandings:
      type: object
      properties:
        team:
          $ref: "#/components/schemas/NBATeam"
        conference_record:
          type: string
        conference_rank:
          type: integer
        division_record:
          type: string
        division_rank:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        home_record:
          type: string
        road_record:
          type: string
        season:
          type: integer
    NBAStats:
      type: object
      properties:
        id:
          type: integer
        min:
          type: string
        fgm:
          type: integer
        fga:
          type: integer
        fg_pct:
          type: number
        fg3m:
          type: integer
        fg3a:
          type: integer
        fg3_pct:
          type: number
        ftm:
          type: integer
        fta:
          type: integer
        ft_pct:
          type: number
        oreb:
          type: integer
        dreb:
          type: integer
        reb:
          type: integer
        ast:
          type: integer
        stl:
          type: integer
        blk:
          type: integer
        turnover:
          type: integer
        pf:
          type: integer
        pts:
          type: integer
        plus_minus:
          type: integer
          nullable: true
          description: Plus/minus for the player in this game
        player:
          $ref: "#/components/schemas/NBAPlayer"
        team:
          $ref: "#/components/schemas/NBATeam"
        game:
          $ref: "#/components/schemas/NBAGame"
    NBATeam:
      type: object
      properties:
        id:
          type: integer
        conference:
          type: string
          enum:
            - East
            - West
        division:
          type: string
          enum:
            - Atlantic
            - Central
            - Southeast
            - Northwest
            - Pacific
            - Southwest
        city:
          type: string
        name:
          type: string
        full_name:
          type: string
        abbreviation:
          type: string
    NBATeamSeasonStat:
      type: object
      properties:
        team:
          $ref: "#/components/schemas/NBATeam"
        season:
          type: integer
          description: Season year
        season_type:
          type: string
          enum:
            - regular
            - playoffs
            - ist
          description: Season type
        stats:
          type: object
          additionalProperties: true
          description: Dynamic stats object with stat names as keys and numeric values. Content varies by category/type combination.
    Pagination:
      type: object
      properties:
        next_cursor:
          type: integer
          description: Cursor for the next page of results
        prev_cursor:
          type: integer
          nullable: true
          description: Cursor for the previous page of results
        per_page:
          type: integer
          description: Number of results per page
    PlayerPropMeta:
      type: object
      description: Metadata for player prop responses (no pagination - all results returned in single response)
      properties:
        per_page:
          type: integer
          description: Total number of results returned
  parameters:
    CursorParam:
      name: cursor
      in: query
      required: false
      schema:
        type: integer
      description: The cursor for pagination
    DatesParam:
      name: dates[]
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          format: date
      style: form
      explode: true
      description: Filter by dates (YYYY-MM-DD)
    PerPageParam:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        maximum: 100
        default: 25
      description: Number of results per page
    PlayerIdsParam:
      name: player_ids[]
      in: query
      required: false
      schema:
        type: array
        items:
          type: integer
      style: form
      explode: true
      description: Filter by player IDs
    SeasonOptionalParam:
      name: season
      in: query
      required: false
      schema:
        type: integer
      description: The season year
    SeasonParam:
      name: season
      in: query
      required: true
      schema:
        type: integer
      description: The season year
    TeamIdsParam:
      name: team_ids[]
      in: query
      required: false
      schema:
        type: array
        items:
          type: integer
      style: form
      explode: true
      description: Filter by team IDs
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequestError:
      description: Bad Request - Invalid parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimitError:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
security:
  - ApiKeyAuth: []
paths:
  /nba/v1/teams:
    get:
      summary: Get NBA teams
      tags:
        - NBA
      parameters:
        - name: division
          in: query
          required: false
          schema:
            type: string
          description: Filter by division
        - name: conference
          in: query
          required: false
          schema:
            type: string
          description: Filter by conference
      responses:
        "200":
          description: List of NBA teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBATeam"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/teams/{id}:
    get:
      summary: Get specific NBA team
      tags:
        - NBA
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Team ID
      responses:
        "200":
          description: Team details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/NBATeam"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/players:
    get:
      summary: Get NBA players
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/TeamIdsParam"
        - $ref: "#/components/parameters/PlayerIdsParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search by player name
        - name: first_name
          in: query
          required: false
          schema:
            type: string
          description: Filter by first name
        - name: last_name
          in: query
          required: false
          schema:
            type: string
          description: Filter by last name
      responses:
        "200":
          description: List of NBA players
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAPlayer"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/players/{id}:
    get:
      summary: Get specific NBA player
      tags:
        - NBA
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Player ID
      responses:
        "200":
          description: Player details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/NBAPlayer"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/games:
    get:
      summary: Get NBA games
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/DatesParam"
        - $ref: "#/components/parameters/TeamIdsParam"
        - name: seasons[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by seasons
        - name: postseason
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by postseason games
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter games after this date
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter games before this date
      responses:
        "200":
          description: List of NBA games
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAGame"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/games/{id}:
    get:
      summary: Get specific NBA game
      tags:
        - NBA
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Game ID
      responses:
        "200":
          description: Game details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/NBAGame"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/stats:
    get:
      summary: Get NBA stats
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/PlayerIdsParam"
        - name: game_ids[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by game IDs
        - $ref: "#/components/parameters/DatesParam"
        - name: seasons[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by seasons
        - name: postseason
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by postseason stats
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter stats after this date
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter stats before this date
        - name: period
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Filter by period (quarter). Defaults to 0, which returns full game totals only.
      responses:
        "200":
          description: List of NBA stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAStats"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/season_averages:
    get:
      summary: Get NBA season averages
      tags:
        - NBA
      parameters:
        - name: season
          in: query
          required: true
          schema:
            type: integer
          description: Season year
        - name: player_id
          in: query
          required: true
          schema:
            type: integer
          description: Player ID
      responses:
        "200":
          description: Season averages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBASeasonAverages"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/season_averages/{type}:
    get:
      summary: Get NBA season averages by type
      tags:
        - NBA
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - general
              - clutch
              - defense
              - shooting
          description: Season average type
        - name: player_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          description: Filter by player IDs
        - name: season
          in: query
          required: true
          schema:
            type: integer
          description: Season year
        - name: season_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - ist
              - playin
          description: Season type
        - name: type
          in: query
          required: true
          schema:
            type: string
          description: Statistics type
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Season averages by type
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBASeasonAverageV2"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/team_season_averages/{category}:
    get:
      summary: Get NBA team season averages by category
      description: |
        Retrieve team season averages for various statistical categories. Each category requires a specific type parameter
        that determines the exact stats returned. The hustle category does not require a type parameter.

        **Available category/type combinations:**
        - general: base, advanced, scoring, misc, opponent, defense, violations
        - clutch: base, advanced, misc, scoring
        - shooting: by_zone_base, by_zone_opponent, 5ft_range_base, 5ft_range_opponent
        - playtype: cut, handoff, isolation, offrebound, offscreen, postup, prballhandler, prrollman, spotup, transition, misc
        - tracking: painttouch, efficiency, speeddistance, defense, elbowtouch, posttouch, passing, drives, rebounding, catchshoot, pullupshot, possessions
        - hustle: (no type parameter required)
        - shotdashboard: overall, pullups, catch_and_shoot, less_than_10_ft
      tags:
        - NBA
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
            enum:
              - general
              - clutch
              - shooting
              - playtype
              - tracking
              - hustle
              - shotdashboard
          description: Statistical category
        - name: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          description: Filter by team IDs
        - name: season
          in: query
          required: true
          schema:
            type: integer
          description: Season year
        - name: season_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - regular
              - playoffs
              - ist
          description: Season type
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Statistics type (required for all categories except hustle)
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Team season averages by category
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBATeamSeasonStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/standings:
    get:
      summary: Get NBA team standings
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/SeasonParam"
      responses:
        "200":
          description: Team standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAStandings"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/players/active:
    get:
      summary: Get active NBA players
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/TeamIdsParam"
        - $ref: "#/components/parameters/PlayerIdsParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search by player name
        - name: first_name
          in: query
          required: false
          schema:
            type: string
        - name: last_name
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: List of active NBA players
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAPlayer"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/player_injuries:
    get:
      summary: Get NBA player injuries
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/TeamIdsParam"
        - $ref: "#/components/parameters/PlayerIdsParam"
      responses:
        "200":
          description: List of NBA player injuries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAPlayerInjury"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/box_scores/live:
    get:
      summary: Get live NBA box scores
      tags:
        - NBA
      responses:
        "200":
          description: Live NBA box scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBABoxScore"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/box_scores:
    get:
      summary: Get NBA box scores for a specific date
      tags:
        - NBA
      parameters:
        - name: date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Date in YYYY-MM-DD format
      responses:
        "200":
          description: NBA box scores for date
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBABoxScore"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/lineups:
    get:
      summary: Get NBA game lineups
      description: |
        Retrieve starting lineups and bench players for NBA games.

        **Important Notes:**
        - Lineup data is only available starting from the 2025 NBA season
        - Lineup data is only available once the game begins
      tags:
        - NBA
      parameters:
        - name: game_ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Array of game IDs to get lineups for
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: NBA lineups for specified games
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBALineup"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/leaders:
    get:
      summary: Get NBA stat leaders
      tags:
        - NBA
      parameters:
        - name: stat_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - ast
              - blk
              - dreb
              - eff
              - fg3a
              - fg3m
              - fg3_pct
              - fga
              - fgm
              - fg_pct
              - fta
              - ftm
              - ft_pct
              - min
              - oreb
              - pts
              - reb
              - stl
              - tov
          description: Type of stat to get leaders for
        - $ref: "#/components/parameters/SeasonParam"
        - name: season_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - regular
              - playoffs
            default: regular
          description: Season type (regular or playoffs). Defaults to regular.
      responses:
        "200":
          description: NBA stat leaders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBALeader"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v2/odds:
    get:
      summary: Get NBA betting odds
      description: Retrieve betting odds for NBA games. Either dates or game_ids is required.
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/DatesParam"
        - name: game_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by game IDs
      responses:
        "200":
          description: NBA betting odds
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBABettingOdd"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v2/odds/player_props:
    get:
      summary: Get NBA player prop betting odds
      description: |
        Retrieve live player prop betting data for NBA games. Player prop data is LIVE and updated in real-time.
        We do not store historical data. As games near completion, many (or all) player props may be removed from sportsbooks.

        **Note:** This endpoint returns all player props for the specified game in a single response. Pagination is not supported.

        The API supports two market types:
        - **over_under**: Traditional over/under markets where users can bet on whether a player will go over or under a specific line value
        - **milestone**: Milestone markets where users bet on whether a player will reach a specific achievement

        Available vendors: draftkings, betway, betrivers, ballybet, betparx, caesars, fanduel, rebet
      tags:
        - NBA
      parameters:
        - name: game_id
          in: query
          required: true
          schema:
            type: integer
          description: The game ID to retrieve player props for (required)
        - name: player_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter props for a specific player
        - name: prop_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - assists
              - assists_1q
              - assists_first3min
              - blocks
              - double_double
              - points
              - points_1q
              - points_assists
              - points_first3min
              - points_rebounds
              - points_rebounds_assists
              - rebounds
              - rebounds_1q
              - rebounds_assists
              - rebounds_first3min
              - steals
              - threes
              - triple_double
          description: Filter by prop type. Supported values include individual stats (points, rebounds, assists, threes, steals, blocks), combo stats (points_assists, points_rebounds, points_rebounds_assists, rebounds_assists), achievements (double_double, triple_double), and various quarter/time-specific props.
      responses:
        "200":
          description: NBA player prop betting odds
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAPlayerProp"
                  meta:
                    $ref: "#/components/schemas/PlayerPropMeta"
              example:
                data:
                  - id: 123
                    game_id: 15907925
                    player_id: 246
                    vendor: draftkings
                    prop_type: points
                    line_value: "25.5"
                    market:
                      type: over_under
                      over_odds: -110
                      under_odds: -110
                    updated_at: "2025-11-23T19:24:39.000Z"
                  - id: 124
                    game_id: 15907925
                    player_id: 246
                    vendor: draftkings
                    prop_type: points
                    line_value: "30.0"
                    market:
                      type: milestone
                      odds: 200
                    updated_at: "2025-11-23T19:24:39.000Z"
                  - id: 125
                    game_id: 15907925
                    player_id: 19
                    vendor: betway
                    prop_type: threes
                    line_value: "4.5"
                    market:
                      type: over_under
                      over_odds: 105
                      under_odds: -125
                    updated_at: "2025-11-23T19:24:39.000Z"
                meta:
                  per_page: 25
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v2/stats/advanced:
    get:
      summary: Get NBA advanced stats (V2)
      description: |
        Retrieve comprehensive advanced statistics for NBA player performances. This V2 endpoint includes
        additional metrics from tracking data, hustle stats, defensive matchups, and usage analytics.

        Includes data from:
        - Box score advanced (PIE, ratings, efficiency metrics)
        - Box score misc (fast break points, second chance points)
        - Box score scoring (shot distribution percentages)
        - Four factors (effective FG%, turnover rate)
        - Hustle stats (deflections, contested shots, loose balls)
        - Defensive matchups (matchup FG%, points allowed)
        - Player tracking (speed, distance, touches)
        - Usage stats (percentage of team stats)
      tags:
        - NBA
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - $ref: "#/components/parameters/PlayerIdsParam"
        - name: game_ids[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by game IDs
        - $ref: "#/components/parameters/DatesParam"
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for filtering (YYYY-MM-DD)
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for filtering (YYYY-MM-DD)
        - name: seasons[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by seasons
        - name: postseason
          in: query
          required: false
          schema:
            type: boolean
          description: Filter for postseason games only
        - name: period
          in: query
          required: false
          schema:
            type: integer
          description: Filter by game period (0 for full game stats)
      responses:
        "200":
          description: NBA advanced stats V2
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAAdvancedStatsV2"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/contracts/teams:
    get:
      summary: Get NBA player contracts by team
      description: Returns all player contracts for a specific team and season. Season defaults to current season if not specified.
      tags:
        - NBA
      parameters:
        - name: team_id
          in: query
          required: true
          schema:
            type: integer
          description: Team ID (required)
        - $ref: "#/components/parameters/SeasonOptionalParam"
      responses:
        "200":
          description: List of player contracts for the team
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAContract"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/contracts/players:
    get:
      summary: Get NBA player contracts
      description: Returns contracts for a specific player, optionally filtered by seasons. Supports pagination.
      tags:
        - NBA
      parameters:
        - name: player_id
          in: query
          required: true
          schema:
            type: integer
          description: Player ID (required)
        - name: seasons[]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by specific seasons
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: List of player contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAContract"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/contracts/players/aggregate:
    get:
      summary: Get aggregated NBA player contract data
      description: Returns multi-year contract aggregates for a specific player, including total value, guarantees, and contract metadata.
      tags:
        - NBA
      parameters:
        - name: player_id
          in: query
          required: true
          schema:
            type: integer
          description: Player ID (required)
      responses:
        "200":
          description: List of aggregated contract data for the player
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAContractAggregate"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /nba/v1/plays:
    get:
      summary: Get NBA play-by-play data
      description: |
        Retrieve play-by-play data for an NBA game.

        Returns all plays for a game in chronological order, including shot attempts, turnovers, fouls, and other game events. Each play includes the game clock, score, and team information.
      tags:
        - NBA
      parameters:
        - name: game_id
          in: query
          required: true
          schema:
            type: integer
          description: Game ID (required)
      responses:
        "200":
          description: Play-by-play data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/NBAPlay"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"