api-ninjas-com Baseball API

openapi: 3.2.0
info:
  title: Ninjas Baseball API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Baseball
  description: MLB schedules, live and final line scores by inning with hits and errors, standings by division, teams and rosters. league defaults to mlb. The free plan covers the current season and masks scores, period and clock of games in progress; paid plans get live data and the three previous seasons; the Business tier and above gets the full season archive.
paths:
  /v1/baseballgames:
    get:
      summary: Get schedules, live scores and final scores
      description: Returns games for one day, a team's season, a season (50 per page; use offset, or limit on paid plans) or one game id. With no parameters, returns today's games.
      operationId: getBaseballGames
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: mlb, the default.'
        schema:
          type: string
          example: mlb
          enum:
          - mlb
      - name: date
        in: query
        required: false
        description: 'Game day in the league''s home time zone (YYYY-MM-DD): US Eastern for the US leagues and MLS, UK time for the Premier League, Central European time for the other European competitions.'
        schema:
          type: string
          example: '2026-10-22'
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: that team''s games in the season.'
        schema:
          type: string
          example: NYY
      - name: season
        in: query
        required: false
        description: Season as the year it starts (2026 = 2026-27 for seasons that span two years). Defaults to the current season.
        schema:
          type: integer
          example: 2026
      - name: season_type
        in: query
        required: false
        description: Only this part of the season.
        schema:
          type: string
          enum:
          - preseason
          - regular
          - postseason
      - name: status
        in: query
        required: false
        description: Only games with this status.
        schema:
          type: string
          enum:
          - scheduled
          - in_progress
          - final
          - postponed
          - canceled
          - suspended
          - delayed
      - name: game_id
        in: query
        required: false
        description: Return one game.
        schema:
          type: string
          example: mlb-20260923-hou-sea
      - name: limit
        in: query
        required: false
        description: Results per page (1-500). Premium only. Default 50.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Results to skip, for paging.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaseballGame'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Baseball
  /v1/baseballstandings:
    get:
      summary: Get league standings
      description: Returns the league table for a season, ordered by league rank, or by conference or division rank when filtered.
      operationId: getBaseballStandings
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: mlb, the default.'
        schema:
          type: string
          example: mlb
          enum:
          - mlb
      - name: season
        in: query
        required: false
        description: Season as the year it starts. Defaults to the current season.
        schema:
          type: integer
          example: 2026
      - name: conference
        in: query
        required: false
        description: Only this conference, e.g. AFC, Eastern or AL.
        schema:
          type: string
      - name: division
        in: query
        required: false
        description: Only this division, e.g. AFC East, Atlantic or NL West.
        schema:
          type: string
          example: Atlantic
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaseballStanding'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Baseball
  /v1/baseballteams:
    get:
      summary: List teams
      description: Lists the teams with league, conference, division and home venue.
      operationId: getBaseballTeams
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: mlb, the default.'
        schema:
          type: string
          example: mlb
          enum:
          - mlb
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: one team.'
        schema:
          type: string
          example: NYY
      - name: conference
        in: query
        required: false
        description: Only teams in this conference.
        schema:
          type: string
      - name: division
        in: query
        required: false
        description: Only teams in this division.
        schema:
          type: string
      - name: active
        in: query
        required: false
        description: false lists former teams that appear in past seasons.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaseballTeam'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Baseball
  /v1/baseballplayers:
    get:
      summary: Get rosters and player profiles
      description: Returns current rosters and player profiles. Provide league with team or name, or a player_id.
      operationId: getBaseballPlayers
      parameters:
      - name: league
        in: query
        required: false
        description: 'Optional: mlb, the default.'
        schema:
          type: string
          example: mlb
          enum:
          - mlb
      - name: team
        in: query
        required: false
        description: 'Team id, abbreviation or name: the team''s current roster.'
        schema:
          type: string
          example: NYY
      - name: name
        in: query
        required: false
        description: Full or partial player name (case and accent insensitive).
        schema:
          type: string
      - name: player_id
        in: query
        required: false
        description: Return one player.
        schema:
          type: string
      - name: position
        in: query
        required: false
        description: Only this position, e.g. SS.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Results per page (1-500). Premium only. Default 50.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Results to skip, for paging.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BaseballPlayer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseballError'
      security:
      - ApiKeyAuth: []
      tags:
      - Baseball
components:
  schemas:
    BaseballError:
      type: object
      properties:
        error:
          type: string
    BaseballTeamRef:
      type: object
      properties:
        team_id:
          type: string
          example: mlb-nyy
          description: Team id, e.g. mlb-nyy.
        name:
          type: string
        abbreviation:
          type: string
          example: NYY
    BaseballTeam:
      type: object
      properties:
        team_id:
          type: string
          example: mlb-nyy
        league:
          type: string
          enum:
          - mlb
        sport:
          type: string
          enum:
          - baseball
        abbreviation:
          type: string
        name:
          type: string
        nickname:
          type: string
        city:
          type: string
        conference:
          type: string
        division:
          type: string
        venue:
          $ref: '#/components/schemas/BaseballVenue'
        active:
          type: boolean
    BaseballGame:
      type: object
      properties:
        game_id:
          type: string
          example: mlb-20260923-hou-sea
          description: Unique, permanent id of the game.
        league:
          type: string
          enum:
          - mlb
        sport:
          type: string
          enum:
          - baseball
        season:
          type: integer
          example: 2026
          description: Year the season starts.
        season_label:
          type: string
          example: 2026-27
        season_type:
          type: string
          enum:
          - preseason
          - regular
          - postseason
        date:
          type: string
          format: date
          description: Game day in US Eastern time.
        start_time:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - scheduled
          - in_progress
          - final
          - postponed
          - canceled
          - suspended
          - delayed
        status_detail:
          type:
          - string
          - 'null'
          description: 'While a game is in progress: top, middle, bottom or end of the inning. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.'
        period:
          type:
          - integer
          - 'null'
          description: Current or last inning played; extra innings continue the count. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        clock:
          type:
          - string
          - 'null'
          description: 'Always null: baseball has no game clock.'
        home_team:
          $ref: '#/components/schemas/BaseballTeamRef'
        away_team:
          $ref: '#/components/schemas/BaseballTeamRef'
        home_score:
          type:
          - integer
          - 'null'
          description: While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        away_score:
          type:
          - integer
          - 'null'
          description: While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
        period_scores:
          type:
          - object
          - 'null'
          description: Runs per inning, with every extra inning. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
          properties:
            home:
              type: array
              items:
                type: integer
            away:
              type: array
              items:
                type: integer
        hits:
          type:
          - object
          - 'null'
          description: hits per team. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
          properties:
            home:
              type: integer
            away:
              type: integer
        errors:
          type:
          - object
          - 'null'
          description: errors per team. While a game is in progress, the free plan receives the string "This field is for premium subscribers only." instead.
          properties:
            home:
              type: integer
            away:
              type: integer
        decided_in:
          type:
          - string
          - 'null'
          enum:
          - regulation
          - extra_innings
          - null
        winner:
          type:
          - string
          - 'null'
          description: team_id of the winner of a final game; null before then.
        venue:
          $ref: '#/components/schemas/BaseballVenue'
        neutral_site:
          type: boolean
        original_date:
          type:
          - string
          - 'null'
          format: date
          description: First scheduled date of a moved game.
        updated_at:
          type: string
          format: date-time
    BaseballVenue:
      type:
      - object
      - 'null'
      properties:
        name:
          type: string
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2
    BaseballPlayer:
      type: object
      properties:
        player_id:
          type: string
          description: Permanent id; it stays the same when a player changes teams.
        league:
          type: string
          enum:
          - mlb
        team:
          allOf:
          - $ref: '#/components/schemas/BaseballTeamRef'
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        position:
          type: string
        jersey_number:
          type:
          - string
          - 'null'
        height_in:
          type:
          - integer
          - 'null'
        height_cm:
          type:
          - integer
          - 'null'
        weight_lb:
          type:
          - integer
          - 'null'
        weight_kg:
          type:
          - integer
          - 'null'
        birth_date:
          type:
          - string
          - 'null'
          format: date
        birth_place:
          type:
          - object
          - 'null'
          properties:
            city:
              type:
              - string
              - 'null'
            state:
              type:
              - string
              - 'null'
            country:
              type:
              - string
              - 'null'
        roster_status:
          type: string
          example: active
        college:
          type: string
        experience_years:
          type: integer
    BaseballStanding:
      type: object
      description: Fields that do not apply to a league are omitted.
      properties:
        league:
          type: string
          enum:
          - mlb
        sport:
          type: string
          enum:
          - baseball
        season:
          type: integer
        season_label:
          type: string
        team:
          $ref: '#/components/schemas/BaseballTeamRef'
        conference:
          type:
          - string
          - 'null'
          description: AL or NL.
        division:
          type:
          - string
          - 'null'
        games_played:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        win_pct:
          type: number
        games_behind:
          type: number
        points_for:
          type: integer
        points_against:
          type: integer
        point_differential:
          type: integer
        streak:
          type: string
          example: W2
        home_record:
          type: string
        away_record:
          type: string
        last_10:
          type: string
        league_rank:
          type: integer
        conference_rank:
          type: integer
        division_rank:
          type: integer
        final:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api