Major League Baseball Person API

openapi: 3.0.1
info:
  title: Stats API Documentation Analytics Person 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: Person
  description: Operations pertaining to players
paths:
  /api/v1/people/{personId}/stats:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: stats_3
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
        x-lookup:
          name: Stat Types
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - 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: metrics
        in: query
        description: Name of metric(s) for metric log stats.  Available metrics in /api/v1/metrics
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MetricType'
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Leagues
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
        x-lookup:
          name: Situation Codes
      - 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: 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: gamesBack
        in: query
        description: Returns results from the last 'X' games played.
        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: eventType
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      - name: pitchType
        in: query
        description: Classification of pitch (fastball, curveball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: hitTrajectory
        in: query
        description: Trajectory of hit (line drive, fly ball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/HitTrajectory'
      - name: batSide
        in: query
        description: Bat side of hitter
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
        x-lookup:
          name: Game Types
      - name: groupBy
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - 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/people/{personId}/stats/metrics:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: statsMetrics
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
        x-lookup:
          name: Stat Types
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - 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: metrics
        in: query
        description: Name of metric(s) for metric log stats.  Available metrics in /api/v1/metrics
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MetricType'
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Leagues
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
        x-lookup:
          name: Situation Codes
      - 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: 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: gamesBack
        in: query
        description: Returns results from the last 'X' games played.
        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: eventType
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      - name: pitchType
        in: query
        description: Classification of pitch (fastball, curveball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: hitTrajectory
        in: query
        description: Trajectory of hit (line drive, fly ball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/HitTrajectory'
      - name: batSide
        in: query
        description: Bat side of hitter
        required: false
        schema:
          type: string
      - name: gameType
        in: query
        description: Comma delimited list of type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
        x-lookup:
          name: Game Types
      - 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: 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/people/{personId}/stats/game/{gamePk}:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: currentGameStats
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: gamePk
        in: path
        description: Unique Primary Key Representing a Game
        required: true
        schema:
          type: integer
          format: int32
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - 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/people/{personId}/stats/game/current:
    get:
      tags:
      - Person
      summary: View a players stats
      operationId: currentGameStats_1
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - 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/people/{personId}/awards:
    get:
      tags:
      - Person
      summary: View a players awards
      operationId: award
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - 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/AwardsRestObject'
  /api/v1/people/{personId}:
    get:
      tags:
      - Person
      summary: View a person(s) biographical information
      description: This endpoint allows you to pull the information of players, coaches and umpires
      operationId: person
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: accent
        in: query
        description: Boolean value to specify wanting a person's name with accents or without
        required: false
        schema:
          type: boolean
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - 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/PeopleRestObject'
  /api/v1/people:
    get:
      tags:
      - Person
      summary: View a person(s) biographical information
      description: This endpoint allows you to pull the information of players, coaches and umpires
      operationId: person_1
      parameters:
      - name: personId
        in: path
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: true
        schema:
          type: integer
          format: int32
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: accent
        in: query
        description: Boolean value to specify wanting a person's name with accents or without
        required: false
        schema:
          type: boolean
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: group
        in: query
        description: Comma delimited list of  categories of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
        x-lookup:
          name: Stat Groups
      - 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/PeopleRestObject'
  /api/v1/people/search:
    get:
      tags:
      - Person
      summary: Search for a player by name
      operationId: search
      parameters:
      - name: names
        in: query
        description: Name a player uses
        required: false
        schema:
          type: array
          items:
            type: string
      - name: personIds
        in: query
        description: 'Comma delimited list of person ID. Format: 1234, 2345'
        required: false
        schema:
          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
        x-lookup:
          name: Sports
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Leagues
      - 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: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
        x-lookup:
          name: League Lists
      - name: active
        in: query
        description: Whether or not a player is active
        required: false
        schema:
          type: boolean
      - name: verified
        in: query
        description: Complete and confirmed all biographical data
        required: false
        schema:
          type: boolean
      - name: rookie
        in: query
        description: Whether or not a player is a rookie
        required: false
        schema:
          type: boolean
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - 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
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PeopleRestObject'
  /api/v1/people/freeAgents:
    get:
      tags:
      - Person
      summary: Get free agents
      operationId: freeAgents
      parameters:
      - name: season
        in: query
        description: Season of play
        required: true
        schema:
          type: string
      - name: order
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/FreeAgentListRestObject'
  /api/v1/people/changes:
    get:
      tags:
      - Person
      summary: View a players change log
      operationId: currentGameStats_2
      parameters:
      - name: updatedSince
        in: query
        description: 'Format: YYYY-MM-DDTHH:MM:SSZ'
        required: true
        schema:
          type: string
          format: date-time
      - 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
        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/PeopleRestObject'
components:
  schemas:
    TeamStatData:
      type: object
      properties:
        requestingUserRole:
          $ref: '#/components/schemas/Role'
        note:
          type: string
        summary:
          type: object
          additionalProperties:
            type: string
          writeOnly: true
        catchersInterference:
          type: integer
          format: int32
        average:
          type: string
        onBasePercentage:
          type: string
        onBasePlusSlugging:
          type: string
        stolenBases:
          type: integer
          format: int32
        caughtStealing:
          type: integer
          format: int32
        slugging:
          type: string
        outs:
          type: integer
          format: int32
        gidp:
          type: integer
          format: int32
        gitp:
          type: integer
          format: int32
        homeRuns:
          type: integer
          format: int32
        numberOfPitches:
          type: integer
          format: int32
        totalBases:
          type: integer
          format: int32
        gidpOpportunites:
          type: integer
          format: int32
        walks:
          type: integer
          format: int32
        hitByPitch:
          type: integer
          format: int32
        strikeouts:
          type: integer
          format: int32
        airOuts:
          type: integer
          format: int32
        goAo:
          type: string
        pitchesPerPlateAppearance:
          type: number
          format: double
        intentionalWalks:
          type: integer
          format: int32
        groundOuts:
          type: integer
          format: int32
        flyOuts:
          type: integer
          format: int32
        games:
          type: integer
          format: int32
        gamesStarted:
          type: integer
          format: int32
        doubles:
          type: integer
          format: int32
        hits:
          type: integer
          format: int32
        triples:
          type: integer
          format: int32
        singles:
          type: integer
          format: int32
        runs:
          type: integer
          format: int32
        atBats:
          type: integer
          format: int32
        pickoffs:
          type: integer
          format: int32
        stolenBasePercentage:
          type: string
        wildPitches:
          type: integer
          format: int32
        sacFlies:
          type: integer
          format: int32
        sacBunts:
          type: integer
          format: int32
        putouts:
          type: integer
          format: int32
        assists:
          type: integer
          format: int32
        chances:
          type: integer
          format: int32
        streak:
          type: integer
          format: int32
        battingOrder:
          type: string
        totalSwings:
          type: integer
          format: int32
        swingsAndMisses:
          type: integer
          format: int32
        ballsInPlay:
          type: integer
          format: int32
        popOuts:
          type: integer
          format: int32
        lineOuts:
          type: integer
          format: int32
        flyHits:
          type: integer
          format: int32
        popHits:
          type: integer
          format: int32
        lineHits:
          type: integer
          format: int32
        groundHits:
          type: integer
          format: int32
        winStreak:
          type: integer
          format: int32
        lossStreak:
          type: integer
          format: int32
        plateAppearances:
          type: integer
          format: int32
        stolenBasePercentageOrNull:
          type: string
        pitchesPerPlateAppearanceStr:
          type: string
    AdditionalBio:
      type: object
      properties:
        id:
          type: integer
          format: int32
        homeTown:
          type: string
    SortOrderEnum:
      type: string
      enum:
      - ASC
      - DESC
    DraftTypeEnum:
      type: string
      enum:
      - JR
      - JS
      - NS
      - NR
      - RV
      - AL
      - RA
      - RT
      - JD
      - AD
    GameStatusRestObject:
      type: object
      properties:
        copyright:
          type: string
        isCurrentBatter:
          type: boolean
        isCurrentPitcher:
          type: boolean
        isOnBench:
          type: boolean
        isSubstitute:
          type: boolean
    WeatherRestObject:
      type: object
      properties:
        copyright:
          type: string
        condition:
          type: string
        temp:
          type: string
        wind:
          type: string
    DraftTypeEnumRestObject:
      type: object
      properties:
        copyright:
          type: string
        code:
          type: string
        description:
          type: string
    BaseballDefenseRestObject:
      type: object
      properties:
        copyright:
          type: string
        pitcher:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        catcher:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        first:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        second:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        third:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        shortstop:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        left:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        center:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        right:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        batter:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        onDeck:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        inHole:
          $ref: '#/components/schemas/BaseballPersonRestObject'
        battingOrder:
          type: integer
          format: int32
        team:
          $ref: '#/components/schemas/BaseballTeamRestObject'
    EducationRestObject:
      type: object
      properties:
        copyright:
          type: string
        highschools:
          type: array
          items:
            $ref: '#/components/schemas/SchoolRestObject'
        colleges:
          type: array
          items:
            $ref: '#/components/schemas/SchoolRestObject'
    StatContainer:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StatType'
        group:
          $ref: '#/components/schemas/StatGroup'
        splits:
          type: array
          items:
            $ref: '#/components/schemas/StatSplits'
        splitsTiedWithOffset:
          type: array
          items:
            $ref: '#/components/schemas/StatSplits'
        splitsTiedWithLimit:
          type: array
          items:
            $ref: '#/components/schemas/StatSplits'
        stats:
          $ref: '#/components/schemas/StatData'
        totalSplits:
          type: integer
          format: int32
        player:
          $ref: '#/components/schemas/BaseballPerson'
        team:
          $ref: '#/components/schemas/BaseballTeam'
        sport:
          $ref: '#/components/schemas/Sport'
        season:
          type: string
        gameType:
          $ref: '#/components/schemas/GameTy

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