Major League Baseball Teams API

openapi: 3.0.1
info:
  title: Stats API Documentation Analytics Teams API
  description: Official API for Major League Baseball.
  version: 2.0.0
servers:
- url: https://statsapi.mlb.com
  description: Production
- url: https://beta-statsapi.mlb.com
  description: Beta
- url: https://qa-statsapi.mlb.com
  description: QA
- url: http://localhost:8080
  description: Local
tags:
- name: Teams
  description: Operations pertaining to teams
paths:
  /api/v1/teams/{teamId}/alumni:
    get:
      tags:
      - Teams
      summary: View all team alumni
      operationId: alumni
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: true
        schema:
          type: string
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          $ref: '#/components/schemas/StatGroup'
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
    post:
      tags:
      - Teams
      operationId: updateAlumni
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: true
        schema:
          type: string
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          $ref: '#/components/schemas/StatGroup'
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: string
  /api/v1/teams/{teamId}/stats:
    get:
      tags:
      - Teams
      summary: 'View stats for an individual team. '
      operationId: stats
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: true
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: sortStat
        in: query
        description: Baseball stat to sort splits by.
        required: false
        schema:
          $ref: '#/components/schemas/BaseballStatsEnum'
      - name: order
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: groupBy
        in: query
        description: Group stats by PLAYER, TEAM, SEASON, VENUE, SPORT or STAT_GROUP
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: opposingPlayerId
        in: query
        description: A unique identifier for the opposing team
        required: false
        schema:
          type: integer
          format: int32
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: string
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/teams/{teamId}/roster:
    get:
      tags:
      - Teams
      summary: View a teams info
      description: This endpoint allows you to pull teams
      operationId: roster
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: rosterType
        in: path
        description: Type of roster. Available types in /api/v1/rosterTypes
        required: true
        schema:
          type: string
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RosterRestObject'
  /api/v1/teams/{teamId}/roster/{rosterType}:
    get:
      tags:
      - Teams
      summary: View a teams info
      description: This endpoint allows you to pull teams
      operationId: roster_1
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: rosterType
        in: path
        description: Type of roster. Available types in /api/v1/rosterTypes
        required: true
        schema:
          type: string
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RosterRestObject'
  /api/v1/teams/{teamId}/personnel:
    get:
      tags:
      - Teams
      summary: View all coaches for a team
      operationId: personnel
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RosterRestObject'
  /api/v1/teams/{teamId}/leaders:
    get:
      tags:
      - Teams
      summary: View team stat leaders
      operationId: leaders
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: leaderCategories
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PersonLeadersEnum'
      - name: season
        in: query
        required: false
        schema:
          type: string
      - name: leaderGameTypes
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
      - name: expand
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ExpandEnum'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: playerPool
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PlayerPoolEnum'
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TeamLeaderContainerRestObject'
  /api/v1/teams/{teamId}/history:
    get:
      tags:
      - Teams
      summary: View historical records for a list of teams
      operationId: allTeams
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: teamIds
        in: query
        description: Comma delimited list of Unique Team identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: startSeason
        in: query
        description: 'Start date for range of data (used with end date optionally). Example: ''2018'' or ''2018.2'''
        required: false
        schema:
          type: string
      - name: endSeason
        in: query
        description: 'End date for range of data (used with start date optionally). Format: ''2018'' or ''2018.2'''
        required: false
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TeamsRestObject'
  /api/v1/teams/history:
    get:
      tags:
      - Teams
      summary: View historical records for a list of teams
      operationId: allTeams_1
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: teamIds
        in: query
        description: Comma delimited list of Unique Team identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: startSeason
        in: query
        description: 'Start date for range of data (used with end date optionally). Example: ''2018'' or ''2018.2'''
        required: false
        schema:
          type: string
      - name: endSeason
        in: query
        description: 'End date for range of data (used with start date optionally). Format: ''2018'' or ''2018.2'''
        required: false
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TeamsRestObject'
  /api/v1/teams/{teamId}/coaches:
    get:
      tags:
      - Teams
      summary: View all coaches for a team
      operationId: coaches
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RosterRestObject'
  /api/v1/teams/{teamId}/affiliates:
    get:
      tags:
      - Teams
      summary: View team and affiliate teams
      operationId: affiliates
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: teamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TeamsRestObject'
  /api/v1/teams/affiliates:
    get:
      tags:
      - Teams
      summary: View team and affiliate teams
      operationId: affiliates_1
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: teamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TeamsRestObject'
  /api/v1/teams/stats:
    get:
      tags:
      - Teams
      summary: View a teams stats
      operationId: stats_1
      parameters:
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: true
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: sortStat
        in: query
        description: Baseball stat to sort splits by.
        required: false
        schema:
          $ref: '#/components/schemas/BaseballStatsEnum'
      - name: order
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: daysBack
        in: query
        description: Returns results from the last 'X' days (Starting from yesterday).
        required: false
        schema:
          type: integer
          format: int32
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: string
      - name: combineSits
        in: query
        description: 'If true, gathers stats where all of the situational criteria are met. If false, returns stats where any of the situational criteria are met. Default: false'
        required: false
        schema:
          type: boolean
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The pointer to start for a return set; used for pagination
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/teams/stats/leaders:
    get:
      tags:
      - Teams
      summary: View leaders for team stats
      operationId: leaders_1
      parameters:
      - name: leaderCategories
        in: query
        description: TBD
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PersonLeadersEnum'
      - name: gameTypes
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
      - name: statType
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/StatType'
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: statGroup
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: daysBack
        in: query
        description: Returns results from the last 'X' days (Starting from yesterday).
        required: false
        schema:
          type: integer
          format: int32
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: string
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The pointer to start for a return set; used for pagination
        required: false
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/LeagueLeaderContainerRestObject'
  /api/v1/teams:
    get:
      tags:
      - Teams
      summary: View info for all teams
      description: This endpoint allows you to pull teams
      operationId: teams
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: divisionId
        in: query
        description: Unique Division Identifier
        required: false
        schema:
          type: integer
          format: int32
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: activeStatus
        in: query
        description: Flag for fetching teams that are currently active (Y), inactive (N), pending (P), or all teams (B)
        required: false
        schema:
          $ref: '#/components/schemas/TeamActiveStatusEnum'
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
      - name: allStarStatuses
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/AllStarEnum'
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsRestObject'
  /api/v1/teams/{teamId}:
    get:
      tags:
      - Teams
      summary: View info for all teams
      description: This endpoint allows you to pull teams
      operationId: teams_1
      parameters:
      - name: teamId
        in: path
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
      - name: divisionId
        in: query
        description: Unique Division Identifier
        required: false
        schema:
          type: integer
          format: int32
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: activeStatus
        in: query
        description: Flag for fetching teams that are currently active (Y), inactive (N), pending (P), or all teams (B)
        required: false
        schema:
          $ref: '#/components/schemas/TeamActiveStatusEnum'
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueLis

# --- truncated at 32 KB (263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-teams-api-openapi.yml