openapi: 3.1.0 info: title: BALLDONTLIE - MLB API version: 1.0.0 description: MLB endpoints for the BallDontLie API. servers: - url: https://api.balldontlie.io description: Production server components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization schemas: OddsLink: type: object additionalProperties: false required: [url, url_template] description: Exactly one of url and url_template is non-null. Templates may contain {state}, {pickType}, or {wagerAmount}; the consuming application supplies these values before navigation. properties: url: type: [string, "null"] description: A complete HTTPS sportsbook URL. url_template: type: [string, "null"] description: An HTTPS sportsbook URL requiring placeholder substitution. Use the sportsbook state code for {state}; BetRivers coupon links also require its pick type and wager amount. oneOf: - properties: url: {type: string} url_template: {type: "null"} - properties: url: {type: "null"} url_template: {type: string} OddsDeeplinks: type: [object, "null"] additionalProperties: false required: [event, selections] description: Available event and selection links, or null when unavailable. Coverage varies by sportsbook, event, and selection. Opening links do not preserve the historical price. properties: event: oneOf: - $ref: "#/components/schemas/OddsLink" - type: "null" selections: type: object description: Available links keyed by the corresponding selection. Missing links are omitted. additionalProperties: $ref: "#/components/schemas/OddsLink" example: event: url: null url_template: https://{state}.betrivers.com/?page=sportsbook#event/1028589932 selections: {} CompetitionStatusState: type: string description: Normalized lifecycle state for cross-sport integrations. Classification may use the sport-specific lifecycle field and other available lifecycle context. `unknown` means the available lifecycle data cannot be safely classified. enum: - scheduled - in_progress - final - postponed - canceled - delayed - suspended - abandoned - unknown DfsSlate: type: object description: A DFS lineup pool with included games and roster slots. Supports DraftKings and FanDuel. required: - id - sport - provider - format - scope - style - salary_cap - event_count - starts_at - last_event_starts_at - status - allow_late_swap - active - updated_at properties: id: type: integer minimum: 1 sport: type: string provider: type: string format: type: string enum: [salary_cap, tiers, snake_draft] scope: type: string enum: [single_event, multi_event] style: type: string salary_cap: type: integer minimum: 0 nullable: true event_count: type: integer minimum: 1 starts_at: type: string format: date-time last_event_starts_at: type: string format: date-time status: type: string allow_late_swap: type: boolean nullable: true active: type: boolean updated_at: type: string format: date-time DfsSlateEvent: type: object description: A real game included in a DFS slate. required: - id - game_id - name - starts_at - away_team_abbreviation - home_team_abbreviation - active properties: id: type: integer minimum: 1 game_id: type: integer minimum: 1 nullable: true description: BALLDONTLIE game ID when a reference is available. name: type: string starts_at: type: string format: date-time away_team_abbreviation: type: string nullable: true home_team_abbreviation: type: string nullable: true active: type: boolean DfsRosterSlot: type: object description: A lineup position required by a DFS slate. required: - id - name - description - instructions - required_count - display_order - active properties: id: type: integer minimum: 1 name: type: string description: type: string nullable: true instructions: type: string nullable: true required_count: type: integer minimum: 1 display_order: type: integer minimum: 0 active: type: boolean DfsSlateDetail: allOf: - $ref: "#/components/schemas/DfsSlate" - type: object required: - events - roster_slots properties: events: type: array items: $ref: "#/components/schemas/DfsSlateEvent" roster_slots: type: array items: $ref: "#/components/schemas/DfsRosterSlot" DfsDraftable: type: object description: A player or team that can be selected for a slate roster slot. required: - id - slate_id - slate_event_id - roster_slot_id - game_id - player_id - team_id - entity_type - first_name - last_name - display_name - short_name - position - salary - status - is_swappable - is_disabled - team_abbreviation - active - updated_at properties: id: type: integer minimum: 1 slate_id: type: integer minimum: 1 slate_event_id: type: integer minimum: 1 roster_slot_id: type: integer minimum: 1 game_id: type: integer minimum: 1 nullable: true description: BALLDONTLIE game ID when a reference is available. player_id: type: integer minimum: 1 nullable: true description: Player ID when available. Null for team entries and when a player relationship is unavailable. team_id: type: integer minimum: 1 nullable: true description: BALLDONTLIE team ID when a reference is available. entity_type: type: string enum: [player, team] first_name: type: string nullable: true last_name: type: string nullable: true display_name: type: string short_name: type: string nullable: true position: type: string nullable: true salary: type: integer minimum: 0 nullable: true status: type: string nullable: true is_swappable: type: boolean nullable: true is_disabled: type: boolean nullable: true team_abbreviation: type: string nullable: true active: type: boolean updated_at: type: string format: date-time DfsPagination: type: object required: - per_page properties: prev_cursor: type: integer minimum: 1 description: Present when the request supplied a cursor. next_cursor: type: integer minimum: 1 description: Present when another page may be available. per_page: type: integer minimum: 1 maximum: 100 DfsSlateListResponse: type: object required: [data, meta] properties: data: type: array items: $ref: "#/components/schemas/DfsSlate" meta: $ref: "#/components/schemas/DfsPagination" DfsSlateDetailResponse: type: object required: [data] properties: data: $ref: "#/components/schemas/DfsSlateDetail" DfsDraftableListResponse: type: object required: [data, meta] properties: data: type: array items: $ref: "#/components/schemas/DfsDraftable" meta: $ref: "#/components/schemas/DfsPagination" DfsValidationError: type: object required: [errors] properties: errors: type: array items: type: object additionalProperties: false required: - param - error properties: param: type: string error: type: string DfsServerError: type: object required: [message] properties: message: type: string const: Internal Server Error Error: type: object properties: error: type: string description: Error message MLBBettingOdd: type: object required: [deeplinks] properties: deeplinks: $ref: "#/components/schemas/OddsDeeplinks" description: "Available sportsbook links. Selection keys: moneyline_home, moneyline_away, spread_home, spread_away, total_over, total_under; only keys corresponding to returned prices and available links are included. Supported books: DraftKings, FanDuel, BetMGM, BetRivers, and Caesars." id: type: integer game_id: type: integer vendor: type: string description: Sportsbook vendor name spread_home_value: type: string nullable: true spread_home_odds: type: integer nullable: true spread_away_value: type: string nullable: true spread_away_odds: type: integer nullable: true moneyline_home_odds: type: integer nullable: true moneyline_away_odds: type: integer nullable: true total_value: type: string nullable: true total_over_odds: type: integer nullable: true total_under_odds: type: integer nullable: true updated_at: type: string format: date-time MLBMarketStatus: type: string enum: - open - locked - suspended - closed - unknown MLBMarketParticipant: type: object required: - type - id - name properties: type: type: string enum: - player - team - other id: type: integer nullable: true description: BALLDONTLIE entity ID when a participant is matched name: type: string MLBBettingMarketOutcome: type: object properties: id: type: integer key: type: string name: type: string type: type: string side: type: string nullable: true line_value: type: string nullable: true handicap: type: string nullable: true american_odds: type: integer nullable: true decimal_odds: type: string nullable: true status: $ref: "#/components/schemas/MLBMarketStatus" participants: type: array items: $ref: "#/components/schemas/MLBMarketParticipant" updated_at: type: string format: date-time MLBBettingMarket: type: object required: [deeplinks] properties: deeplinks: $ref: "#/components/schemas/OddsDeeplinks" description: "Available event links. Expanded markets currently return an empty selections object." id: type: integer game_id: type: integer vendor: type: string key: type: string description: Open-ended normalized market key name: type: string description: Sportsbook market display name type: type: string period: type: string scope: type: string team_side: type: string nullable: true line_value: type: string nullable: true status: $ref: "#/components/schemas/MLBMarketStatus" is_live: type: boolean updated_at: type: string format: date-time outcomes: type: array items: $ref: "#/components/schemas/MLBBettingMarketOutcome" MLBOpeningPlayerProp: type: object required: [deeplinks] properties: deeplinks: $ref: "#/components/schemas/OddsDeeplinks" description: "Available sportsbook links. Selection keys: over and under for over/under props; yes for milestone props; only keys corresponding to returned prices and available links are included. Supported books: DraftKings, FanDuel, BetMGM, BetRivers, and Caesars." id: type: integer format: int64 game_id: type: integer player_id: type: integer vendor: type: string enum: - betmgm - betrivers - caesars - draftkings - fanatics - fanduel prop_type: type: string description: Open-ended MLB player prop type. Common examples include hits, home_runs, total_bases, runs_scored, hits_runs_rbis, and pitcher_strikeouts. line_value: type: string market: type: object properties: type: type: string enum: - over_under - milestone over_odds: type: integer nullable: true under_odds: type: integer nullable: true odds: type: integer nullable: true description: Used for milestone market type opened_at: type: string format: date-time MLBOpeningBettingOdd: type: object required: [deeplinks] properties: deeplinks: $ref: "#/components/schemas/OddsDeeplinks" description: "Available sportsbook links. Selection keys: moneyline_home, moneyline_away, spread_home, spread_away, total_over, total_under; only keys corresponding to returned prices and available links are included. Supported books: DraftKings, FanDuel, BetMGM, BetRivers, and Caesars." id: type: integer game_id: type: integer vendor: type: string description: Sportsbook vendor name spread_home_value: type: string nullable: true spread_home_odds: type: integer nullable: true spread_away_value: type: string nullable: true spread_away_odds: type: integer nullable: true moneyline_home_odds: type: integer nullable: true moneyline_away_odds: type: integer nullable: true total_value: type: string nullable: true total_over_odds: type: integer nullable: true total_under_odds: type: integer nullable: true opened_at: type: string format: date-time MLBGame: type: object required: - status_state properties: id: type: integer home_team_name: type: string away_team_name: type: string home_team: $ref: "#/components/schemas/MLBTeam" away_team: $ref: "#/components/schemas/MLBTeam" season: type: integer postseason: type: boolean season_type: type: string enum: - spring_training - regular - postseason description: The type of season (spring_training, regular, or postseason) date: type: string format: date-time home_team_data: type: object properties: hits: type: integer runs: type: integer errors: type: integer inning_scores: type: array items: type: integer away_team_data: type: object properties: hits: type: integer runs: type: integer errors: type: integer inning_scores: type: array items: type: integer venue: type: string attendance: type: integer conference_play: type: boolean period: type: integer nullable: true clock: type: integer nullable: true display_clock: type: string nullable: true scoring_summary: type: array items: type: object properties: play: type: string inning: type: string period: type: string away_score: type: integer home_score: type: integer status: type: string status_state: allOf: - $ref: "#/components/schemas/CompetitionStatusState" description: Normalized lifecycle state derived from `status` and other available lifecycle context; `status` remains unchanged. MLBPitchDetail: type: object properties: pitch_number: type: integer description: Pitch number within the plate appearance balls: type: integer nullable: true description: Ball count before this pitch strikes: type: integer nullable: true description: Strike count before this pitch pitch_call: type: string nullable: true description: Umpire call (B=ball, S=strike, X=in play) description: type: string nullable: true description: Detailed pitch outcome label pitch_call_code: type: string nullable: true description: Raw pitch call code from the data source call_name: type: string nullable: true description: Human-readable pitch call name pitch_type_code: type: string nullable: true description: Short pitch type code (FF, SL, CU, CH, etc.) pitch_type: type: string nullable: true description: Full pitch type name (e.g., "4-Seam Fastball") release_speed: type: number nullable: true description: Pitch velocity at release (mph) plate_speed: type: number nullable: true description: Pitch velocity at plate (mph) spin_rate: type: number nullable: true description: Spin rate (RPM) release_extension: type: number nullable: true description: Pitcher extension (feet) plate_time: type: number nullable: true description: Time to reach plate (seconds) plate_x: type: number nullable: true description: Horizontal plate location (feet from center) plate_z: type: number nullable: true description: Vertical plate location (feet above ground) strike_zone: type: integer nullable: true description: Strike zone region (1-14) strike_zone_top: type: number nullable: true strike_zone_bottom: type: number nullable: true horizontal_movement: type: number nullable: true description: Horizontal pitch movement (inches) vertical_movement: type: number nullable: true description: Vertical pitch movement (inches) horizontal_break: type: number nullable: true vertical_break: type: number nullable: true induced_vertical_break: type: number nullable: true description: Gravity-corrected vertical break (inches) release_pos_x: type: number nullable: true release_pos_y: type: number nullable: true release_pos_z: type: number nullable: true velocity_x: type: number nullable: true velocity_y: type: number nullable: true velocity_z: type: number nullable: true acceleration_x: type: number nullable: true acceleration_y: type: number nullable: true acceleration_z: type: number nullable: true bat_speed: type: number nullable: true description: Bat speed on contact (mph) exit_velocity: type: number nullable: true description: Exit velocity off the bat (mph). Only populated for balls in play. launch_angle: type: number nullable: true description: Launch angle off the bat (degrees). Only populated for balls in play. hit_distance: type: integer nullable: true description: Projected hit distance (feet). Only populated for balls in play. expected_batting_average: type: number nullable: true description: Expected batting average based on exit velocity and launch angle. Only populated for balls in play. is_barrel: type: boolean nullable: true description: Whether the batted ball qualifies as a barrel. Only populated for balls in play. hit_coordinate_x: type: number nullable: true description: Horizontal hit coordinate on the field spray chart. Only populated for balls in play. hit_coordinate_y: type: number nullable: true description: Vertical hit coordinate on the field spray chart. Only populated for balls in play. is_in_zone: type: boolean nullable: true description: Whether the pitch crossed the strike zone is_swing: type: boolean nullable: true description: Whether the batter swung at the pitch is_whiff: type: boolean nullable: true description: Whether the swing missed the pitch is_contact: type: boolean nullable: true description: Whether the swing made contact is_chase: type: boolean nullable: true description: Whether the batter chased a pitch outside the zone is_command: type: boolean nullable: true description: Whether the pitch counted as a commanded pitch expected_woba: type: number nullable: true description: Expected weighted on-base value for the pitch outcome woba_value: type: number nullable: true description: Weighted on-base value for the pitch outcome woba_denom: type: number nullable: true description: Weighted on-base denominator for the pitch outcome expected_slugging: type: number nullable: true description: Expected slugging value for the pitch outcome game_pitch_count: type: integer nullable: true description: Total pitches in the game so far pitcher_pitch_count: type: integer nullable: true description: Pitcher's pitch count MLBPlateAppearance: type: object properties: batter_id: type: integer description: Player ID of the batter pitcher_id: type: integer description: Player ID of the pitcher inning: type: integer half_inning: type: string description: "\"top\" or \"bottom\"" pa_number: type: integer description: Plate appearance number within the game outs: type: integer nullable: true description: Number of outs at the start of the plate appearance batter_side: type: string nullable: true description: Batter stance (L or R) pitcher_hand: type: string nullable: true description: Pitcher throwing hand (L or R) result: type: string nullable: true description: Outcome of the plate appearance (e.g., "Strikeout", "Single") is_ball_in_play_out: type: boolean nullable: true runner_on_first: type: boolean nullable: true runner_on_second: type: boolean nullable: true runner_on_third: type: boolean nullable: true pitches: type: array items: $ref: "#/components/schemas/MLBPitchDetail" description: Individual pitches in this plate appearance MLBPlay: type: object properties: game_id: type: integer order: type: integer description: Sequential play order number type: type: string nullable: true description: Type of play (e.g., "Start Batter/Pitcher", "Play Result", "Fly Out") text: type: string nullable: true description: Human-readable play description home_score: type: integer away_score: type: integer inning: type: integer inning_type: type: string nullable: true description: "\"Top\" or \"Bottom\"" scoring_play: type: boolean score_value: type: integer nullable: true outs: type: integer nullable: true balls: type: integer nullable: true strikes: type: integer nullable: true batter_id: type: integer nullable: true description: Player ID of the batter pitcher_id: type: integer nullable: true description: Player ID of the pitcher pitch_type: type: string nullable: true pitch_velocity: type: number nullable: true description: Pitch velocity in mph hit_coordinate_x: type: number nullable: true hit_coordinate_y: type: number nullable: true trajectory: type: string nullable: true description: Hit trajectory (F=fly, G=ground, L=line drive) MLBGameLineup: type: object properties: id: type: integer game_id: type: integer player: $ref: "#/components/schemas/MLBPlayer" team: $ref: "#/components/schemas/MLBTeam" batting_order: type: integer nullable: true description: Batting order position (1-9), null for probable pitchers not in the batting lineup position: type: string nullable: true description: "Position abbreviation (SS, CF, DH, SP, etc.)" is_probable_pitcher: type: boolean description: Whether this player is the probable starting pitcher MLBPlayer: type: object properties: id: type: integer first_name: type: string last_name: type: string full_name: type: string debut_year: type: integer nullable: true jersey: type: string college: type: string position: type: string active: type: boolean birth_place: type: string dob: type: string age: type: integer nullable: true height: type: string weight: type: string draft: type: string bats_throws: type: string team: $ref: "#/components/schemas/MLBTeam" MLBPlayerProp: type: object required: [deeplinks] properties: deeplinks: $ref: "#/components/schemas/OddsDeeplinks" description: "Available sportsbook links. Selection keys: over and under for over/under props; yes for milestone props; only keys corresponding to returned prices and available links are included. Supported books: DraftKings, FanDuel, BetMGM, BetRivers, and Caesars." id: type: integer game_id: type: integer player_id: type: integer vendor: type: string enum: - betmgm - betrivers - caesars - draftkings - fanatics - fanduel prop_type: type: string description: Open-ended MLB player prop type. Common examples include hits, home_runs, total_bases, runs_scored, hits_runs_rbis, and pitcher_strikeouts. line_value: type: string market: type: object properties: type: type: string enum: - over_under - milestone over_odds: type: integer nullable: true under_odds: type: integer nullable: true odds: type: integer nullable: true description: Used for milestone market type updated_at: type: string format: date-time MLBSeasonStats: type: object properties: player: $ref: "#/components/schemas/MLBPlayer" team_name: type: string season: type: integer postseason: type: boolean season_type: type: string enum: - spring_training - regular - postseason batting_gp: type: integer batting_ab: type: integer batting_r: type: integer batting_h: type: integer batting_avg: type: number batting_2b: type: integer batting_3b: type: integer batting_hr: type: integer batting_rbi: type: integer batting_tb: type: integer batting_bb: type: integer batting_so: type: integer batting_sb: type: integer batting_obp: type: number batting_slg: type: number batting_ops: type: number batting_war: type: number pitching_gp: type: integer pitching_gs: type: integer pitching_qs: type: integer pitching_w: type: integer pitching_l: type: integer pitching_era: type: number pitching_sv: type: integer pitching_hld: type: integer pitching_ip: type: number pitching_h: type: integer pitching_er: type: integer pitching_hr: type: integer pitching_bb: type: integer pitching_whip: type: number pitching_k: type: integer pitching_k_per_9: type: number pitching_war: type: number fielding_gp: type: integer fielding_gs: type: integer fielding_fip: type: number fielding_tc: type: integer fielding_po: type: integer fielding_a: type: integer fielding_fp: type: number fielding_e: type: integer fielding_dp: type: integer fielding_rf: type: number fielding_dwar: type: number fielding_pb: type: integer fielding_cs: type: integer fielding_cs_percent: type: number fielding_sba: type: integer MLBStandings: type: object properties: team: $ref: "#/components/schemas/MLBTeam" league_name: type: string league_short_name: type: string division_name: type: string division_short_name: type: string wins: type: integer losses: type: integer win_percent: type: number games_behind: type: number streak: type: integer last_ten_games: type: string season: type: integer clinch_indicator: type: string elimination_number: type: integer wild_card_elimination_number: type: integer league_rank: type: integer sport_rank: type: integer division_rank: type: integer league_games_back: type: number sport_games_back: type: number division_games_back: type: number conference_games_back: type: number division_leader: type: boolean division_champ: type: boolean runs_allowed: type: integer runs_scored: type: integer run_differential: type: integer home_wins: type: integer home_losses: type: integer away_wins: type: integer away_losses: type: integer last_updated: type: string records: type: object day_wins: type: integer day_losses: type: integer night_wins: type: integer night_losses: type: integer one_run_wins: type: integer one_run_losses: type: integer extra_inning_wins: type: integer extra_inning_losses: type: integer MLBStats: type: object properties: player: $ref: "#/components/schemas/MLBPlayer" team: $ref: "#/components/schemas/MLBTeam" game_id: type: integer description: The ID of the game this stat belongs to team_name: type: string at_bats: type: integer nullable: true runs: type: integer nullable: true hits: type: integer nullable: true rbi: type: integer nullable: true hr: type: integer nullable: true bb: type: integer nullable: true k: type: integer nullable: true avg: type: number nullable: true obp: type: number nullable: true slg: type: number nullable: true doubles: type: integer nullable: true description: Doubles (from detailed box score) triples: type: integer nullable: true intentional_walks: type: integer nullable: true hit_by_pitch: type: integer nullable: true stolen_bases: type: integer nullable: true caught_stealing: type: integer nullable: true plate_appearances: type: integer nullable: true total_bases: type: integer nullable: true left_on_base: type: integer nullable: true fly_outs: type: integer nullable: true ground_outs: type: integer nullable: true line_outs: type: integer nullable: true pop_outs: type: integer nullable: true air_outs: type: integer nullable: true gidp: type: integer nullable: true description: Grounded into double play sac_bunts: type: integer nullable: true sac_flies: type: integer nullable: true ip: type: number nullable: true description: Innings pitched p_hits: type: integer nullable: true description: Hits allowed (pitching) p_runs: type: integer nullable: true description: Runs allowed (pitching) er: type: integer nullable: true description: Earned runs p_bb: type: integer nullable: true description: Walks allowed (pitching) p_k: type: integer nullable: true description: Strikeouts (pitching) p_hr: type: integer nullable: true description: Home runs allowed (pitching) pitch_count: type: integer nullable: true strikes: type: integer nullable: true era: type: number nullable: true batters_faced: type: integer nullable: true pitching_outs: type: integer nullable: true wins: type: integer nullable: true losses: type: integer nullable: true saves: type: integer nullable: true holds: type: integer nullable: true blown_saves: type: integer nullable: true games_started: type: integer nullable: true wild_pitches: type: integer nullable: true balks: type: integer nullable: true pitching_hbp: type: integer nullable: true description: Hit batters (pitching) inherited_runners: type: integer nullable: true inherited_runners_scored: type: integer nullable: true putouts: type: integer nullable: true assists: type: integer nullable: true errors: type: integer nullable: true fielding_chances: type: integer nullable: true fielding_pct: type: number nullable: true MLBTeam: type: object properties: id: type: integer slug: type: string abbreviation: type: string display_name: type: string short_display_name: type: string name: type: string location: type: string league: type: string enum: - American - National division: type: string enum: - East - Central - West MLBTeamSeasonStats: type: object properties: team: $ref: "#/components/schemas/MLBTeam" team_name: type: string postseason: type: boolean season_type: type: string enum: - spring_training - regular - postseason season: type: integer gp: type: integer batting_ab: type: integer batting_r: type: integer batting_h: type: integer batting_2b: type: integer batting_3b: type: integer batting_hr: type: integer batting_rbi: type: integer batting_tb: type: integer batting_bb: type: integer batting_so: type: integer batting_sb: type: integer batting_avg: type: number batting_obp: type: number batting_slg: type: number batting_ops: type: number pitching_w: type: integer pitching_l: type: integer pitching_era: type: number pitching_sv: type: integer pitching_cg: type: integer pitching_sho: type: integer pitching_qs: type: integer pitching_ip: type: number pitching_h: type: integer pitching_er: type: integer pitching_hr: type: integer pitching_bb: type: integer pitching_k: type: integer pitching_oba: type: number pitching_whip: type: number fielding_e: type: integer fielding_fp: type: number fielding_tc: type: integer fielding_po: type: integer fielding_a: type: integer MLBPitchTypeStatsBase: type: object properties: id: type: integer player_id: type: integer pitch_type: type: string description: Short pitch type code pitch_name: type: string nullable: true description: Full pitch type name pitch_count: type: integer pitch_usage_percent: type: number nullable: true zone_count: type: integer zone_percent: type: number nullable: true chase_count: type: integer chase_percent: type: number nullable: true command_count: type: integer command_percent: type: number nullable: true swing_count: type: integer whiff_count: type: integer whiff_percent: type: number nullable: true contact_count: type: integer contact_percent: type: number nullable: true called_strike_count: type: integer called_ball_count: type: integer pa_count: type: integer at_bat_count: type: integer hit_count: type: integer single_count: type: integer double_count: type: integer triple_count: type: integer home_run_count: type: integer walk_count: type: integer strikeout_count: type: integer total_bases: type: integer damage_count: type: integer ba: type: number nullable: true slg: type: number nullable: true woba: type: number nullable: true xwoba: type: number nullable: true walk_zone_count: type: integer walk_chase_count: type: integer walk_command_count: type: integer strikeout_zone_count: type: integer strikeout_chase_count: type: integer strikeout_command_count: type: integer MLBPitchTypeGameStat: allOf: - $ref: "#/components/schemas/MLBPitchTypeStatsBase" - type: object properties: game_id: type: integer MLBPitchTypeSeasonStat: allOf: - $ref: "#/components/schemas/MLBPitchTypeStatsBase" - type: object properties: season: type: integer season_type: type: string enum: - regular - postseason games_backfilled: type: integer season_pitch_count: type: integer last_game_date: type: string format: date nullable: true 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: DfsSlateIdsParam: name: slate_ids[] in: query required: false description: Filter by DFS slate IDs. style: form explode: true schema: type: array items: type: integer minimum: 1 maximum: 9007199254740991 DfsProvidersParam: name: providers[] in: query required: false description: Filter by provider. Supported values are draftkings and fanduel. style: form explode: true schema: type: array items: type: string minLength: 1 maxLength: 100 DfsFormatsParam: name: formats[] in: query required: false description: Filter by lineup format. style: form explode: true schema: type: array items: type: string enum: [salary_cap, tiers, snake_draft] DfsScopesParam: name: scopes[] in: query required: false description: Filter by single-game or multi-game scope. style: form explode: true schema: type: array items: type: string enum: [single_event, multi_event] DfsActiveParam: name: active in: query required: false description: Return current records by default; set false for inactive history. schema: type: boolean default: true DfsStartDateParam: name: start_date in: query required: false description: Include slates whose event window overlaps this date or later. schema: type: string format: date DfsEndDateParam: name: end_date in: query required: false description: Include slates whose event window overlaps this date or earlier. schema: type: string format: date DfsCursorParam: name: cursor in: query required: false description: Cursor returned by the previous page. schema: type: integer minimum: 1 maximum: 9007199254740991 DfsPerPageParam: name: per_page in: query required: false description: Maximum records to return. schema: type: integer minimum: 1 maximum: 100 default: 25 DfsGameIdsParam: name: game_ids[] in: query required: false description: Filter by BALLDONTLIE game IDs. style: form explode: true schema: type: array items: type: integer minimum: 1 maximum: 2147483647 DfsPlayerIdsParam: name: player_ids[] in: query required: false description: Filter by BALLDONTLIE player IDs. style: form explode: true schema: type: array items: type: integer minimum: 1 maximum: 2147483647 DfsTeamIdsParam: name: team_ids[] in: query required: false description: Filter by BALLDONTLIE team IDs. style: form explode: true schema: type: array items: type: integer minimum: 1 maximum: 2147483647 DfsPositionsParam: name: positions[] in: query required: false description: Filter by provider roster position. style: form explode: true schema: type: array items: type: string minLength: 1 maxLength: 100 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 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 GameIdsParam: name: game_ids[] in: query required: false schema: type: array items: type: integer style: form explode: true description: Filter by game IDs PitchTypeParam: name: pitch_type in: query required: false schema: type: string description: Filter by pitch type code RegularPostseasonParam: name: season_type in: query required: false schema: type: string enum: - regular - postseason description: Filter by regular season or postseason SortOrderParam: name: sort_order in: query required: false schema: type: string enum: - asc - desc description: Sort direction. Defaults to `asc`. MLBPitchTypeGameSortByParam: name: sort_by in: query required: false schema: type: string enum: - pitch_count - pitch_usage_percent - zone_percent - chase_percent - command_percent - swing_count - whiff_percent - contact_percent - called_strike_count - called_ball_count - pa_count - at_bat_count - hit_count - home_run_count - walk_count - strikeout_count - total_bases - damage_count - ba - slg - woba - xwoba description: Attribute to sort by MLBPitchTypeSeasonSortByParam: name: sort_by in: query required: false schema: type: string enum: - pitch_count - pitch_usage_percent - zone_percent - chase_percent - command_percent - swing_count - whiff_percent - contact_percent - called_strike_count - called_ball_count - pa_count - at_bat_count - hit_count - home_run_count - walk_count - strikeout_count - total_bases - damage_count - ba - slg - woba - xwoba - last_game_date description: Attribute to sort by responses: DfsBadRequest: description: Invalid DFS request parameters. content: application/json: schema: $ref: "#/components/schemas/DfsValidationError" DfsUnauthorized: description: Missing API key or GOAT access. content: text/plain: schema: type: string const: Unauthorized DfsNotFound: description: DFS slate not found. content: text/plain: schema: type: string const: Not Found DfsRateLimited: description: Request limit exceeded. content: text/html: schema: type: string const: Too many requests, please try again later. DfsServerFailure: description: Internal server error. content: application/json: schema: $ref: "#/components/schemas/DfsServerError" 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: /mlb/v1/teams: get: summary: Get MLB teams tags: - MLB parameters: - name: division in: query required: false schema: type: string description: Filter by division - name: league in: query required: false schema: type: string description: Filter by league responses: "200": description: List of MLB teams content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBTeam" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/teams/{id}: get: summary: Get specific MLB team tags: - MLB 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/MLBTeam" "401": $ref: "#/components/responses/UnauthorizedError" "404": $ref: "#/components/responses/NotFoundError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/players: get: summary: Get MLB players tags: - MLB 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 MLB players content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPlayer" 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" /mlb/v1/players/{id}: get: summary: Get specific MLB player tags: - MLB 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/MLBPlayer" "401": $ref: "#/components/responses/UnauthorizedError" "404": $ref: "#/components/responses/NotFoundError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/player_injuries: get: summary: Get MLB player injuries tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/TeamIdsParam" - $ref: "#/components/parameters/PlayerIdsParam" responses: "200": description: List of MLB player injuries content: application/json: schema: type: object properties: data: type: array items: type: object properties: player: $ref: "#/components/schemas/MLBPlayer" date: type: string format: date-time return_date: type: string format: date-time type: type: string detail: type: string side: type: string status: type: string long_comment: type: string short_comment: type: string 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" /mlb/v1/players/active: get: summary: Get active MLB players tags: - MLB 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 active MLB players content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPlayer" 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" /mlb/v1/games: get: summary: Get MLB games tags: - MLB 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: season_type in: query required: false schema: type: string enum: - spring_training - regular - postseason description: Filter by season type (spring_training, regular, or postseason). Takes precedence over postseason parameter. responses: "200": description: List of MLB games content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBGame" 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" /mlb/v1/games/{id}: get: summary: Get specific MLB game tags: - MLB 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/MLBGame" "401": $ref: "#/components/responses/UnauthorizedError" "404": $ref: "#/components/responses/NotFoundError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/stats: get: summary: Get MLB stats tags: - MLB 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 - name: seasons[] in: query required: false schema: type: array items: type: integer style: form explode: true description: Filter by seasons responses: "200": description: List of MLB stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBStats" 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" /mlb/v1/standings: get: summary: Get MLB team standings tags: - MLB parameters: - $ref: "#/components/parameters/SeasonParam" responses: "200": description: Team standings content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBStandings" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/season_stats: get: summary: Get MLB season stats tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/SeasonParam" - $ref: "#/components/parameters/PlayerIdsParam" - name: team_id in: query required: false schema: type: integer description: Filter by team ID - name: postseason in: query required: false schema: type: boolean description: Get postseason stats - name: season_type in: query required: false schema: type: string enum: - spring_training - regular - postseason description: Filter by season type. Takes precedence over postseason parameter. - name: sort_by in: query required: false schema: type: string description: Attribute to sort by - name: sort_order in: query required: false schema: type: string enum: - asc - desc description: Sort order responses: "200": description: MLB season stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBSeasonStats" 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" /mlb/v1/teams/season_stats: get: summary: Get MLB team season stats tags: - MLB parameters: - $ref: "#/components/parameters/SeasonParam" - name: team_id in: query required: false schema: type: integer description: Filter by team ID - name: postseason in: query required: false schema: type: boolean description: Get postseason stats - name: season_type in: query required: false schema: type: string enum: - spring_training - regular - postseason description: Filter by season type. Takes precedence over postseason parameter. responses: "200": description: MLB team season stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBTeamSeasonStats" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/players/splits: get: summary: Get MLB player splits description: Get player splits grouped by split_category (e.g., vs RHP/LHP, by month, by opponent, etc.) tags: - MLB parameters: - name: player_id in: query required: true schema: type: integer description: Player ID - name: season in: query required: true schema: type: integer description: Season year responses: "200": description: Player splits grouped by split_category content: application/json: schema: type: object properties: data: type: object description: Splits grouped by split_category (e.g., "split", "byDayMonth", "byOpponent") additionalProperties: type: array items: type: object properties: player: $ref: "#/components/schemas/MLBPlayer" season: type: integer category: type: string description: batting or pitching split_category: type: string description: Category of split (e.g., split, byDayMonth, byOpponent) split_name: type: string description: Name of the split (e.g., "vs RHP", "April") split_abbreviation: type: string nullable: true at_bats: type: integer nullable: true runs: type: integer nullable: true hits: type: integer nullable: true doubles: type: integer nullable: true triples: type: integer nullable: true home_runs: type: integer nullable: true rbis: type: integer nullable: true walks: type: integer nullable: true hit_by_pitch: type: integer nullable: true strikeouts: type: integer nullable: true stolen_bases: type: integer nullable: true caught_stealing: type: integer nullable: true avg: type: number format: float nullable: true obp: type: number format: float nullable: true slg: type: number format: float nullable: true ops: type: number format: float nullable: true era: type: number format: float nullable: true wins: type: integer nullable: true losses: type: integer nullable: true saves: type: integer nullable: true save_opportunities: type: integer nullable: true games_played: type: integer nullable: true games_started: type: integer nullable: true complete_games: type: integer nullable: true innings_pitched: type: number format: float nullable: true hits_allowed: type: integer nullable: true runs_allowed: type: integer nullable: true earned_runs: type: integer nullable: true home_runs_allowed: type: integer nullable: true walks_allowed: type: integer nullable: true strikeouts_pitched: type: integer nullable: true opponent_avg: type: number format: float nullable: true "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/players/versus: get: summary: Get MLB player vs player matchups description: Get head-to-head batting statistics for batter against pitchers for a specific team, or pitcher against batters from a specific team tags: - MLB parameters: - name: player_id in: query required: true schema: type: integer description: Player ID (batter or pitcher) - name: opponent_team_id in: query required: true schema: type: integer description: Opponent team ID responses: "200": description: List of player vs player matchups content: application/json: schema: type: object properties: data: type: array items: type: object properties: player: $ref: "#/components/schemas/MLBPlayer" opponent_player: $ref: "#/components/schemas/MLBPlayer" opponent_team: $ref: "#/components/schemas/MLBTeam" at_bats: type: integer nullable: true hits: type: integer nullable: true doubles: type: integer nullable: true triples: type: integer nullable: true home_runs: type: integer nullable: true rbi: type: integer nullable: true walks: type: integer nullable: true strikeouts: type: integer nullable: true avg: type: number format: float nullable: true obp: type: number format: float nullable: true slg: type: number format: float nullable: true ops: type: number format: float nullable: true "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/plays: get: summary: Get MLB play-by-play data description: > Returns play-by-play data for a specific game including game state, scoring plays, and batted ball details. Plays are ordered by `order` ascending by default. Set `sort_order=desc` to return the latest plays first. Keep the same `sort_order` when following pagination cursors. tags: - MLB parameters: - name: game_id in: query required: true schema: type: integer description: The game ID (required) - $ref: "#/components/parameters/SortOrderParam" - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" responses: "200": description: MLB play-by-play data content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPlay" 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" /mlb/v1/plate_appearances: get: summary: Get MLB plate appearance data description: Returns plate appearance data for a specific game. Each plate appearance includes the outcome and all individual pitches with detailed advanced pitch metrics. All plate appearances for the game are returned in a single response (no pagination). tags: - MLB parameters: - name: game_id in: query required: true schema: type: integer description: The game ID (required) responses: "200": description: MLB plate appearance data content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPlateAppearance" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/pitcher_pitch_type_game_stats: get: summary: Get MLB pitcher pitch type game stats description: Returns per-game pitcher pitch-type usage, command, whiff/contact, and damage metrics. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/PlayerIdsParam" - $ref: "#/components/parameters/GameIdsParam" - $ref: "#/components/parameters/TeamIdsParam" - name: season in: query required: false schema: type: integer description: Filter by season year - $ref: "#/components/parameters/RegularPostseasonParam" - $ref: "#/components/parameters/PitchTypeParam" - $ref: "#/components/parameters/MLBPitchTypeGameSortByParam" - $ref: "#/components/parameters/SortOrderParam" responses: "200": description: MLB pitcher pitch type game stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPitchTypeGameStat" 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" /mlb/v1/hitter_pitch_type_game_stats: get: summary: Get MLB hitter pitch type game stats description: Returns per-game hitter pitch-type usage, command, whiff/contact, and damage metrics. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/PlayerIdsParam" - $ref: "#/components/parameters/GameIdsParam" - $ref: "#/components/parameters/TeamIdsParam" - name: season in: query required: false schema: type: integer description: Filter by season year - $ref: "#/components/parameters/RegularPostseasonParam" - $ref: "#/components/parameters/PitchTypeParam" - $ref: "#/components/parameters/MLBPitchTypeGameSortByParam" - $ref: "#/components/parameters/SortOrderParam" responses: "200": description: MLB hitter pitch type game stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPitchTypeGameStat" 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" /mlb/v1/pitcher_pitch_type_season_stats: get: summary: Get MLB pitcher pitch type season stats description: Returns season-level pitcher pitch-type usage, command, whiff/contact, and damage metrics. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/SeasonParam" - $ref: "#/components/parameters/PlayerIdsParam" - $ref: "#/components/parameters/RegularPostseasonParam" - $ref: "#/components/parameters/PitchTypeParam" - $ref: "#/components/parameters/MLBPitchTypeSeasonSortByParam" - $ref: "#/components/parameters/SortOrderParam" responses: "200": description: MLB pitcher pitch type season stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPitchTypeSeasonStat" 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" /mlb/v1/hitter_pitch_type_season_stats: get: summary: Get MLB hitter pitch type season stats description: Returns season-level hitter pitch-type usage, command, whiff/contact, and damage metrics. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - $ref: "#/components/parameters/SeasonParam" - $ref: "#/components/parameters/PlayerIdsParam" - $ref: "#/components/parameters/RegularPostseasonParam" - $ref: "#/components/parameters/PitchTypeParam" - $ref: "#/components/parameters/MLBPitchTypeSeasonSortByParam" - $ref: "#/components/parameters/SortOrderParam" responses: "200": description: MLB hitter pitch type season stats content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPitchTypeSeasonStat" 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" /mlb/v1/odds: get: summary: Get MLB betting odds description: Retrieve betting odds for MLB games. Either dates or game_ids is required. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - name: dates in: query required: false schema: type: array items: type: string format: date style: form explode: true description: Filter by specific dates (YYYY-MM-DD format) - 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: MLB betting odds content: application/json: example: data: - id: 147862608 game_id: 1830 vendor: betrivers deeplinks: event: url: https://pa.betrivers.com/?page=sportsbook#event/1028589932 url_template: null selections: moneyline_home: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195318|{wagerAmount} moneyline_away: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195319|{wagerAmount} spread_home_value: '-3.5' spread_home_odds: 185 spread_away_value: '3.5' spread_away_odds: -245 moneyline_home_odds: -4800 moneyline_away_odds: 1600 total_value: '6.5' total_over_odds: 120 total_under_odds: -154 updated_at: '2026-02-15T12:04:32.251Z' meta: next_cursor: 147862610 per_page: 25 schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBBettingOdd" 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" /mlb/v1/odds/markets: get: summary: Get all current MLB betting markets description: | Retrieve the current market catalog for one MLB game. This open-ended endpoint includes game, team, inning, player, comparison, milestone, and other market structures without requiring market names or keys to come from a fixed list. Complete current catalogs are available for DraftKings and FanDuel. Sportsbooks supported by the simplified odds or player-props endpoints may not appear here until complete market catalogs are available. Markets are paginated as complete units. Outcomes may have null prices while their status is `locked` or `suspended`. Use `/mlb/v1/odds/player_props` when you only need the simplified single-player over/under and milestone projection. tags: - MLB parameters: - name: game_id in: query required: true schema: type: integer description: Game ID to retrieve markets for - name: vendors in: query required: false schema: type: array items: type: string style: form explode: true description: Filter by sportsbook vendors. Complete current catalogs are available for `draftkings` and `fanduel`. - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" responses: "200": description: Current MLB betting markets content: application/json: example: data: - id: 91821 game_id: 1830 vendor: draftkings deeplinks: event: url: https://sportsbook.draftkings.com/event/31953063 url_template: null selections: {} key: hits_runs_stolen_bases_milestones name: Example Player Hits + Runs + Stolen Bases type: other period: match scope: other team_side: null line_value: null status: open is_live: false updated_at: '2026-07-20T12:04:32.251Z' outcomes: - id: 441902 key: '1' name: 1+ type: other side: null line_value: '1' handicap: null american_odds: 125 decimal_odds: '2.250000' status: open participants: - type: player id: 1956 name: Example Player updated_at: '2026-07-20T12:04:32.251Z' - id: 441903 key: '2' name: 2+ type: other side: null line_value: '2' handicap: null american_odds: null decimal_odds: null status: locked participants: - type: player id: 1956 name: Example Player updated_at: '2026-07-20T12:04:32.251Z' meta: next_cursor: 91821 per_page: 25 schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBBettingMarket" 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" /mlb/v1/odds/opening: get: summary: Get MLB opening betting odds description: Retrieve historical opening betting odds. Coverage is limited to the most recently completed season and ongoing seasons where available. Requires GOAT tier. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - name: game_ids in: query required: false schema: type: array items: type: integer style: form explode: true description: Filter by game IDs - name: dates in: query required: false schema: type: array items: type: string format: date style: form explode: true description: Filter by game dates responses: "200": description: Opening odds content: application/json: example: data: - id: 7119985 game_id: 4549 vendor: betrivers deeplinks: event: url: https://pa.betrivers.com/?page=sportsbook#event/1028589932 url_template: null selections: moneyline_home: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195318|{wagerAmount} moneyline_away: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195319|{wagerAmount} spread_home_value: null spread_home_odds: null spread_away_value: null spread_away_odds: null moneyline_home_odds: -115 moneyline_away_odds: 100 total_value: null total_over_odds: null total_under_odds: null opened_at: '2021-04-16T00:00:00.000Z' meta: next_cursor: 7119985 per_page: 1 schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBOpeningBettingOdd" 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" /mlb/v1/odds/player_props: get: summary: Get MLB player prop betting odds description: | Retrieve live player prop betting data for MLB 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 Prop types are open-ended. Common examples include: - Batter props: hits, home_runs, total_bases, rbis, stolen_bases, singles, doubles, triples, walks, strikeouts, runs_scored, and hits_runs_rbis - Pitcher props: pitcher_strikeouts, pitcher_outs, pitcher_hits_allowed, pitcher_walks, pitcher_earned_runs, and pitcher_record_a_win Newly available compatible single-player markets can appear without a documentation enum update. Use `/mlb/v1/odds/markets` for the complete current market catalog, including structures that do not fit this simplified response. Available vendors: betmgm, betrivers, caesars, draftkings, fanatics, fanduel tags: - MLB 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 description: Filter by an open-ended prop type string. - name: vendors in: query required: false schema: type: array items: type: string enum: - betmgm - betrivers - caesars - draftkings - fanatics - fanduel style: form explode: true description: Filter by specific sportsbook vendors (e.g., draftkings, fanduel). If not provided, returns props from all available vendors. responses: "200": description: MLB player prop betting odds content: application/json: example: data: - id: 4312298296 game_id: 1830 player_id: 1956 vendor: betrivers deeplinks: event: url: https://pa.betrivers.com/?page=sportsbook#event/1028589932 url_template: null selections: over: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195318|{wagerAmount} under: url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195319|{wagerAmount} prop_type: stolen_bases line_value: '0.5' market: type: over_under over_odds: 800 under_odds: -1600 updated_at: '2026-02-15T12:04:32.355Z' schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBPlayerProp" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/odds/player_props/opening: get: summary: Get MLB opening player prop odds description: Retrieve historical opening player prop betting odds. Coverage is limited to the most recently completed season and ongoing seasons where available. Requires GOAT tier. tags: - MLB parameters: - name: game_id in: query required: true schema: type: integer description: The game ID to retrieve opening player props for - 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 description: Filter by prop type - name: vendors in: query required: false schema: type: array items: type: string style: form explode: true description: Filter by sportsbook vendors responses: "200": description: Opening odds content: application/json: example: data: - id: 1929082136 game_id: 5057774 player_id: 53 vendor: betrivers deeplinks: event: url: https://pa.betrivers.com/?page=sportsbook#event/1028589932 url_template: null selections: 'yes': url: null url_template: >- https://{state}.betrivers.com/?page=sportsbook#event/1028589932?coupon={pickType}|4365195318|{wagerAmount} prop_type: first_home_run line_value: '0.5' market: type: milestone odds: 1500 opened_at: '2026-03-19T22:16:09.038Z' meta: per_page: 1 schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBOpeningPlayerProp" meta: $ref: "#/components/schemas/PlayerPropMeta" "400": $ref: "#/components/responses/BadRequestError" "401": $ref: "#/components/responses/UnauthorizedError" "429": $ref: "#/components/responses/RateLimitError" "500": $ref: "#/components/responses/ServerError" /mlb/v1/dfs/slates: get: summary: Get MLB DFS slates description: | Returns DraftKings and FanDuel daily fantasy lineup pools. A slate identifies its format, event window, salary cap, and whether it covers one or multiple games. Use the slate detail endpoint for included events and roster slots, then request draftables for selectable players or teams and their slate-specific salaries. Requires GOAT tier. Current slates are returned by default; use active=false for inactive historical snapshots. tags: - MLB parameters: - $ref: "#/components/parameters/DfsSlateIdsParam" - $ref: "#/components/parameters/DfsProvidersParam" - $ref: "#/components/parameters/DfsFormatsParam" - $ref: "#/components/parameters/DfsScopesParam" - $ref: "#/components/parameters/DfsActiveParam" - $ref: "#/components/parameters/DfsStartDateParam" - $ref: "#/components/parameters/DfsEndDateParam" - $ref: "#/components/parameters/DfsCursorParam" - $ref: "#/components/parameters/DfsPerPageParam" responses: "200": description: Paginated DFS slates. content: application/json: schema: $ref: "#/components/schemas/DfsSlateListResponse" "400": $ref: "#/components/responses/DfsBadRequest" "401": $ref: "#/components/responses/DfsUnauthorized" "429": $ref: "#/components/responses/DfsRateLimited" "500": $ref: "#/components/responses/DfsServerFailure" /mlb/v1/dfs/slates/{id}: get: summary: Get a MLB DFS slate description: | Returns one slate with its included real-game events and lineup roster slots. Event game_id values use BALLDONTLIE game IDs when a reference is available. The active flags preserve the state of historical slate members. Requires GOAT tier. tags: - MLB parameters: - name: id in: path required: true description: DFS slate ID. schema: type: integer minimum: 1 maximum: 9007199254740991 responses: "200": description: DFS slate detail. content: application/json: schema: $ref: "#/components/schemas/DfsSlateDetailResponse" "400": $ref: "#/components/responses/DfsBadRequest" "401": $ref: "#/components/responses/DfsUnauthorized" "404": $ref: "#/components/responses/DfsNotFound" "429": $ref: "#/components/responses/DfsRateLimited" "500": $ref: "#/components/responses/DfsServerFailure" /mlb/v1/dfs/draftables: get: summary: Get MLB DFS draftables description: | Returns players or teams that can be selected for a slate roster slot, including position, salary, availability, and linked BALLDONTLIE entities when available. game_id, player_id, or team_id can be null when unavailable. Team entries have null player_id. For provider selection, filter slates with providers[], then pass their IDs as slate_ids[]. A player can appear in multiple roster slots with different salaries. Salary can be null for formats such as snake drafts. Status is the provider availability designation, separate from is_disabled and is_swappable. Check updated_at for snapshot freshness. These endpoints do not describe every contest restriction or scoring rule. Current draftables are returned by default; use active=false for inactive history. Requires GOAT tier. tags: - MLB parameters: - $ref: "#/components/parameters/DfsSlateIdsParam" - $ref: "#/components/parameters/DfsGameIdsParam" - $ref: "#/components/parameters/DfsPlayerIdsParam" - $ref: "#/components/parameters/DfsTeamIdsParam" - $ref: "#/components/parameters/DfsPositionsParam" - $ref: "#/components/parameters/DfsActiveParam" - $ref: "#/components/parameters/DfsCursorParam" - $ref: "#/components/parameters/DfsPerPageParam" responses: "200": description: Paginated DFS draftables. content: application/json: schema: $ref: "#/components/schemas/DfsDraftableListResponse" "400": $ref: "#/components/responses/DfsBadRequest" "401": $ref: "#/components/responses/DfsUnauthorized" "429": $ref: "#/components/responses/DfsRateLimited" "500": $ref: "#/components/responses/DfsServerFailure" /mlb/v1/lineups: get: summary: Get MLB game lineups description: Get pre-game batting lineups and probable pitchers for MLB games. Lineups typically appear 1-2 hours before first pitch. Lineup data is available starting from the 2026 season. tags: - MLB parameters: - $ref: "#/components/parameters/CursorParam" - $ref: "#/components/parameters/PerPageParam" - 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: List of game lineups content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/MLBGameLineup" 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"