openapi: 3.1.0
info:
  title: BALLDONTLIE - Bundesliga API
  version: 1.0.0
  description: Bundesliga endpoints for the BallDontLie API.
servers:
  - url: https://api.balldontlie.io
    description: Production server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
    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
    SoccerBettingOdd:
      type: object
      properties:
        id:
          type: integer
          description: Betting odd ID
        match_id:
          type: integer
          description: Match ID
        vendor:
          type: string
          description: Sportsbook vendor name
        moneyline_home_odds:
          type: integer
          nullable: true
          description: Home team moneyline odds
        moneyline_away_odds:
          type: integer
          nullable: true
          description: Away team moneyline odds
        moneyline_draw_odds:
          type: integer
          nullable: true
          description: Draw moneyline odds
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    SoccerOpeningPlayerProp:
      type: object
      description: Soccer player prop betting data
      required:
        - id
        - match_id
        - player_id
        - vendor
        - prop_type
        - line_value
        - market
        - updated_at
      properties:
        id:
          type: integer
          format: int64
          description: Unique player prop ID
        match_id:
          type: integer
          description: Match ID
        player_id:
          type: integer
          description: Player ID
        vendor:
          type: string
          description: Sportsbook vendor name
          enum:
            - draftkings
            - fanduel
            - caesars
        prop_type:
          type: string
          description: Type of player prop
          enum:
            - anytime_goal
            - assists
            - first_goal
            - first_half_goal
            - goals_assists
            - header_goal
            - last_goal
            - outside_box_goal
            - saves
            - second_half_goal
            - shots
            - shots_on_target
            - tackles
          example: anytime_goal
        line_value:
          type: string
          description: The line value for the prop
          example: "0.5"
        market:
          oneOf:
            - $ref: "#/components/schemas/SoccerPlayerPropMarketOverUnder"
            - $ref: "#/components/schemas/SoccerPlayerPropMarketMilestone"
          description: Market information - either over_under or milestone type
        opened_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this prop was last updated
    SoccerOpeningBettingOdd:
      type: object
      properties:
        id:
          type: integer
          description: Betting odd ID
        match_id:
          type: integer
          description: Match ID
        vendor:
          type: string
          description: Sportsbook vendor name
        moneyline_home_odds:
          type: integer
          nullable: true
          description: Home team moneyline odds
        moneyline_away_odds:
          type: integer
          nullable: true
          description: Away team moneyline odds
        moneyline_draw_odds:
          type: integer
          nullable: true
          description: Draw moneyline odds
        opened_at:
          type: string
          format: date-time
          description: Opening odds timestamp
    SoccerMatch:
      type: object
      properties:
        id:
          type: integer
        season:
          type: integer
        home_team_id:
          type: integer
          nullable: true
        away_team_id:
          type: integer
          nullable: true
        date:
          type: string
          format: date-time
        name:
          type: string
          nullable: true
        short_name:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        status_detail:
          type: string
          nullable: true
        home_score:
          type: integer
          nullable: true
        away_score:
          type: integer
          nullable: true
        venue_name:
          type: string
          nullable: true
        venue_city:
          type: string
          nullable: true
        attendance:
          type: integer
          nullable: true
        referee_name:
          type: string
          nullable: true
        referee_country:
          type: string
          nullable: true
        round_number:
          type: integer
          nullable: true
        venue_latitude:
          type: number
          nullable: true
        venue_longitude:
          type: number
          nullable: true
        venue_capacity:
          type: integer
          nullable: true
        venue_stadium_name:
          type: string
          nullable: true
        home_formation:
          type: string
          nullable: true
        away_formation:
          type: string
          nullable: true
        home_manager_name:
          type: string
          nullable: true
        away_manager_name:
          type: string
          nullable: true
        first_half_home_score:
          type: integer
          nullable: true
        first_half_away_score:
          type: integer
          nullable: true
        second_half_home_score:
          type: integer
          nullable: true
        second_half_away_score:
          type: integer
          nullable: true
    SoccerMatchEvent:
      type: object
      properties:
        id:
          type: integer
        match_id:
          type: integer
        team_id:
          type: integer
          nullable: true
        event_type:
          type: string
          description: Type of event (e.g., goal, yellow_card, red_card, substitution)
        event_time:
          type: integer
          nullable: true
          description: Time in minutes when the event occurred
        period:
          type: integer
          nullable: true
          description: Period/half when the event occurred
        player:
          $ref: "#/components/schemas/SoccerPlayer"
          nullable: true
        secondary_player:
          $ref: "#/components/schemas/SoccerPlayer"
          nullable: true
          description: Second player involved (e.g., substitute coming in, assisting player)
        goal_type:
          type: string
          nullable: true
        is_own_goal:
          type: boolean
    SoccerMatchLineup:
      type: object
      properties:
        match_id:
          type: integer
        team_id:
          type: integer
        player:
          $ref: "#/components/schemas/SoccerPlayer"
        is_starter:
          type: boolean
        position:
          type: string
          nullable: true
        position_abbreviation:
          type: string
          nullable: true
        formation_position:
          type: string
          nullable: true
        jersey_number:
          type: string
          nullable: true
    SoccerPlayer:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        display_name:
          type: string
        short_name:
          type: string
          nullable: true
        date_of_birth:
          type: string
          format: date
          nullable: true
        age:
          type: integer
          nullable: true
        height:
          type: string
          nullable: true
        weight:
          type: string
          nullable: true
        citizenship:
          type: string
          nullable: true
        team_ids:
          type: array
          nullable: true
          items:
            type: integer
        preferred_foot:
          type: string
          nullable: true
          description: Preferred kicking foot (left/right/both)
    SoccerPlayerInjury:
      type: object
      description: Current soccer player injury report
      properties:
        id:
          type: integer
          description: Injury report ID
        player:
          $ref: "#/components/schemas/SoccerPlayer"
        team:
          $ref: "#/components/schemas/SoccerTeam"
        position:
          type: string
          nullable: true
          description: Player position from the injury source
        injury_type:
          type: string
          nullable: true
          description: Injury or absence type
        status:
          type: string
          description: Injury status, such as OUT, GTD, or SUS
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the current injury snapshot was refreshed
    SoccerPlayerMatchStats:
      type: object
      properties:
        match_id:
          type: integer
        player_id:
          type: integer
        team_id:
          type: integer
        appearances:
          type: integer
        goals:
          type: integer
        assists:
          type: integer
        shots_total:
          type: integer
          nullable: true
        shots_on_target:
          type: integer
          nullable: true
        fouls_committed:
          type: integer
          nullable: true
        fouls_suffered:
          type: integer
          nullable: true
        offsides:
          type: integer
          nullable: true
        saves:
          type: integer
          nullable: true
        yellow_cards:
          type: integer
        red_cards:
          type: integer
        own_goals:
          type: integer
        rating:
          type: number
          nullable: true
          description: Match rating on a 0-10 scale
        minutes_played:
          type: integer
          nullable: true
        expected_goals:
          type: number
          nullable: true
        expected_assists:
          type: number
          nullable: true
        key_passes:
          type: integer
          nullable: true
        passes_total:
          type: integer
          nullable: true
        passes_accurate:
          type: integer
          nullable: true
        long_balls_total:
          type: integer
          nullable: true
        long_balls_accurate:
          type: integer
          nullable: true
        crosses_total:
          type: integer
          nullable: true
        crosses_accurate:
          type: integer
          nullable: true
        dribbles_attempted:
          type: integer
          nullable: true
        dribbles_completed:
          type: integer
          nullable: true
        duels_won:
          type: integer
          nullable: true
        duels_lost:
          type: integer
          nullable: true
        aerial_duels_won:
          type: integer
          nullable: true
        aerial_duels_lost:
          type: integer
          nullable: true
        tackles:
          type: integer
          nullable: true
        tackles_won:
          type: integer
          nullable: true
        interceptions:
          type: integer
          nullable: true
        clearances:
          type: integer
          nullable: true
        ball_recoveries:
          type: integer
          nullable: true
        touches:
          type: integer
          nullable: true
        possession_lost:
          type: integer
          nullable: true
        was_fouled:
          type: integer
          nullable: true
        big_chances_created:
          type: integer
          nullable: true
        big_chances_missed:
          type: integer
          nullable: true
        blocked_shots:
          type: integer
          nullable: true
        hit_woodwork:
          type: integer
          nullable: true
        total_progression:
          type: number
          nullable: true
        ball_carries_count:
          type: integer
          nullable: true
        ball_carries_distance:
          type: number
          nullable: true
        goalkeeper_saves:
          type: integer
          nullable: true
        saves_inside_box:
          type: integer
          nullable: true
        penalty_saves:
          type: integer
          nullable: true
        punches:
          type: integer
          nullable: true
        keeper_sweeper_total:
          type: integer
          nullable: true
        keeper_sweeper_accurate:
          type: integer
          nullable: true
        shirt_number:
          type: integer
          nullable: true
        lineup_position:
          type: string
          nullable: true
        was_substitute:
          type: boolean
          nullable: true
    SoccerPlayerProp:
      type: object
      description: Soccer player prop betting data
      required:
        - id
        - match_id
        - player_id
        - vendor
        - prop_type
        - line_value
        - market
        - updated_at
      properties:
        id:
          type: integer
          description: Unique player prop ID
        match_id:
          type: integer
          description: Match ID
        player_id:
          type: integer
          description: Player ID
        vendor:
          type: string
          description: Sportsbook vendor name
          enum:
            - draftkings
            - fanduel
            - caesars
        prop_type:
          type: string
          description: Type of player prop
          enum:
            - anytime_goal
            - assists
            - first_goal
            - first_half_goal
            - goals_assists
            - header_goal
            - last_goal
            - outside_box_goal
            - saves
            - second_half_goal
            - shots
            - shots_on_target
            - tackles
          example: anytime_goal
        line_value:
          type: string
          description: The line value for the prop
          example: "0.5"
        market:
          oneOf:
            - $ref: "#/components/schemas/SoccerPlayerPropMarketOverUnder"
            - $ref: "#/components/schemas/SoccerPlayerPropMarketMilestone"
          description: Market information - either over_under or milestone type
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this prop was last updated
    SoccerPlayerPropMarketMilestone:
      type: object
      description: Milestone market type for soccer player props
      required:
        - type
        - odds
      properties:
        type:
          type: string
          enum:
            - milestone
          description: Market type identifier
        odds:
          type: integer
          description: American odds for milestone bet
    SoccerPlayerPropMarketOverUnder:
      type: object
      description: Over/under market type for soccer player props
      required:
        - type
        - over_odds
        - under_odds
      properties:
        type:
          type: string
          enum:
            - over_under
          description: Market type identifier
        over_odds:
          type: integer
          description: American odds for over bet
        under_odds:
          type: integer
          description: American odds for under bet
    SoccerRoster:
      type: object
      properties:
        team_id:
          type: integer
        player:
          $ref: "#/components/schemas/SoccerPlayer"
        season:
          type: integer
        jersey_number:
          type: string
          nullable: true
        position:
          type: string
          nullable: true
        position_abbreviation:
          type: string
          nullable: true
        is_active:
          type: boolean
    SoccerStanding:
      type: object
      properties:
        team:
          $ref: "#/components/schemas/SoccerTeam"
        season:
          type: integer
        rank:
          type: integer
        rank_change:
          type: integer
          nullable: true
        group_name:
          type: string
          nullable: true
          description: Group identifier for tournament-style leagues (e.g., UCL Group A)
        note:
          type: string
          nullable: true
        games_played:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        draws:
          type: integer
        points:
          type: integer
        goals_for:
          type: integer
        goals_against:
          type: integer
        goal_differential:
          type: integer
        points_per_game:
          type: number
          nullable: true
    SoccerTeam:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        short_name:
          type: string
          nullable: true
        abbreviation:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
    SoccerTeamMatchStats:
      type: object
      properties:
        match_id:
          type: integer
        team_id:
          type: integer
        possession_pct:
          type: number
          nullable: true
        shots:
          type: integer
          nullable: true
        shots_on_target:
          type: integer
          nullable: true
        fouls:
          type: integer
          nullable: true
        yellow_cards:
          type: integer
          nullable: true
        red_cards:
          type: integer
          nullable: true
        corners:
          type: integer
          nullable: true
        passes:
          type: integer
          nullable: true
        pass_accuracy_pct:
          type: number
          nullable: true
        expected_goals:
          type: number
          nullable: true
        big_chances:
          type: integer
          nullable: true
        big_chances_missed:
          type: integer
          nullable: true
        shots_off_target:
          type: integer
          nullable: true
        shots_blocked:
          type: integer
          nullable: true
        shots_inside_box:
          type: integer
          nullable: true
        shots_outside_box:
          type: integer
          nullable: true
        hit_woodwork:
          type: integer
          nullable: true
        offsides:
          type: integer
          nullable: true
        throw_ins:
          type: integer
          nullable: true
        goal_kicks:
          type: integer
          nullable: true
        free_kicks:
          type: integer
          nullable: true
        long_balls_total:
          type: integer
          nullable: true
        long_balls_accurate:
          type: integer
          nullable: true
        crosses_total:
          type: integer
          nullable: true
        crosses_accurate:
          type: integer
          nullable: true
        ground_duels_won:
          type: integer
          nullable: true
        ground_duels_total:
          type: integer
          nullable: true
        aerial_duels_won:
          type: integer
          nullable: true
        aerial_duels_total:
          type: integer
          nullable: true
        dribbles_completed:
          type: integer
          nullable: true
        dribbles_total:
          type: integer
          nullable: true
        tackles:
          type: integer
          nullable: true
        interceptions:
          type: integer
          nullable: true
        clearances:
          type: integer
          nullable: true
        saves:
          type: integer
          nullable: true
        big_saves:
          type: integer
          nullable: true
    SoccerMatchShot:
      type: object
      properties:
        id:
          type: integer
        match_id:
          type: integer
        player_id:
          type: integer
        team_id:
          type: integer
        is_home:
          type: boolean
        shot_type:
          type: string
          description: One of goal, save, miss, block, post
        situation:
          type: string
          nullable: true
        body_part:
          type: string
          nullable: true
        goal_type:
          type: string
          nullable: true
        xg:
          type: number
          nullable: true
        xgot:
          type: number
          nullable: true
        player_x:
          type: number
          nullable: true
        player_y:
          type: number
          nullable: true
        goal_mouth_x:
          type: number
          nullable: true
        goal_mouth_y:
          type: number
          nullable: true
        block_x:
          type: number
          nullable: true
        block_y:
          type: number
          nullable: true
        time_minute:
          type: integer
        added_time:
          type: integer
          nullable: true
        time_seconds:
          type: integer
          nullable: true
    SoccerMatchMomentumPoint:
      type: object
      properties:
        match_id:
          type: integer
        minute:
          type: number
        value:
          type: number
    SoccerMatchBestPlayer:
      type: object
      properties:
        match_id:
          type: integer
        player_id:
          type: integer
        team_id:
          type: integer
        is_home:
          type: boolean
        side_rank:
          type: integer
        is_man_of_match:
          type: boolean
        rating:
          type: number
          nullable: true
    SoccerMatchAvgPosition:
      type: object
      properties:
        match_id:
          type: integer
        player_id:
          type: integer
        team_id:
          type: integer
        is_home:
          type: boolean
        avg_x:
          type: number
        avg_y:
          type: number
    SoccerMatchHeatmap:
      type: object
      description: |
        Per-player heatmap dots for a match. Heatmap data is published only after a
        match concludes; in-progress matches return zero heatmap rows.
      properties:
        match_id:
          type: integer
        player_id:
          type: integer
        team_id:
          type: integer
          nullable: true
        dots:
          type: array
          items:
            type: object
            properties:
              x:
                type: integer
              y:
                type: integer
        dot_count:
          type: integer
    SoccerMatchPregameForm:
      type: object
      description: Pre-match team-form summary
      properties:
        match_id:
          type: integer
        team_id:
          type: integer
        is_home:
          type: boolean
        avg_rating:
          type: number
          nullable: true
        position:
          type: integer
          nullable: true
        value:
          type: string
          nullable: true
          description: Recent-points summary string
        form:
          type: array
          nullable: true
          minItems: 0
          maxItems: 5
          items:
            type: string
            enum:
              - W
              - D
              - L
          description: Up to 5 of the team's most-recent results (newest first)
  parameters:
    CursorParam:
      name: cursor
      in: query
      required: false
      schema:
        type: integer
      description: The cursor for pagination
    PerPageParam:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        maximum: 100
        default: 25
      description: Number of results per page
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequestError:
      description: Bad Request - Invalid parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimitError:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
security:
  - ApiKeyAuth: []
paths:
  /bundesliga/v1/teams:
    get:
      summary: Get Bundesliga teams
      description: Get all teams participating in the Bundesliga for a given season
      tags:
        - Bundesliga
      parameters:
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: Filter by season year. Defaults to the current season if omitted.
      responses:
        "200":
          description: List of Bundesliga teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerTeam"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /bundesliga/v1/rosters:
    get:
      summary: Get Bundesliga team rosters
      description: Get player roster information for a specific team and season
      tags:
        - Bundesliga
      parameters:
        - name: team_id
          in: query
          required: true
          schema:
            type: integer
          description: Team ID
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: Filter by season year
      responses:
        "200":
          description: Team roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerRoster"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /bundesliga/v1/players:
    get:
      summary: Get Bundesliga players
      description: Get players with optional filtering by team or search term. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by team IDs
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search players by name
      responses:
        "200":
          description: List of Bundesliga players
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerPlayer"
                  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"
  /bundesliga/v1/player_injuries:
    get:
      summary: Get Bundesliga player injuries
      description: Retrieve the current Bundesliga player injury snapshot. Supports filtering by player IDs, team IDs, or injury status. Requires GOAT tier access.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: player_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by player IDs
        - name: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by team IDs
        - name: statuses
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by injury statuses, such as OUT, GTD, or SUS
      responses:
        "200":
          description: List of Bundesliga player injuries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerPlayerInjury"
                  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"
  /bundesliga/v1/standings:
    get:
      summary: Get Bundesliga standings
      description: Get league standings for a specific season
      tags:
        - Bundesliga
      parameters:
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: Filter by season year
      responses:
        "200":
          description: League standings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerStanding"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /bundesliga/v1/matches:
    get:
      summary: Get Bundesliga matches
      description: Get matches with optional filtering by season, dates, or teams. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: season
          in: query
          required: false
          schema:
            type: integer
          description: Filter by season year
        - 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: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by team IDs
      responses:
        "200":
          description: List of matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatch"
                  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"
  /bundesliga/v1/match_events:
    get:
      summary: Get Bundesliga match events
      description: Get match events (goals, cards, substitutions, etc.) with optional filtering by matches. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
      responses:
        "200":
          description: List of match events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchEvent"
                  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"
  /bundesliga/v1/match_lineups:
    get:
      summary: Get Bundesliga match lineups
      description: Get match lineups (starting and substitute players) with optional filtering by matches. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
      responses:
        "200":
          description: List of match lineups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchLineup"
                  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"
  /bundesliga/v1/player_match_stats:
    get:
      summary: Get Bundesliga player match statistics
      description: Get player match statistics with optional filtering by matches or players. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
        - name: player_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by player IDs
      responses:
        "200":
          description: List of player match statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerPlayerMatchStats"
                  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"
  /bundesliga/v1/team_match_stats:
    get:
      summary: Get Bundesliga team match statistics
      description: Get team match statistics with optional filtering by matches or teams. Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
        - name: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by team IDs
      responses:
        "200":
          description: List of team match statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerTeamMatchStats"
                  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"
  /bundesliga/v1/odds:
    get:
      summary: Get Bundesliga betting odds
      description: Retrieve betting odds for Bundesliga matches. Supports filtering by match IDs or dates. Bundesliga odds include moneyline odds for home, away, and draw outcomes only (no spreads or totals). Supports pagination.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
        - 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)
      responses:
        "200":
          description: Bundesliga betting odds
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerBettingOdd"
                  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"
  /bundesliga/v1/odds/opening:
    get:
      summary: Get Bundesliga 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:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by match IDs
        - name: dates
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: date
          style: form
          explode: true
          description: Filter by match dates
      responses:
        "200":
          description: Opening odds
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerOpeningBettingOdd"
                  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"

  /bundesliga/v1/odds/player_props:
    get:
      summary: Get Bundesliga player prop betting odds
      description: |
        Retrieve live player prop betting data for Bundesliga matches. Player prop data is LIVE and updated in real-time.
        We do not store historical data. As matches near completion, many (or all) player props may be removed from sportsbooks.

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

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

        Available vendors: draftkings, fanduel, caesars (more coming soon!)
      tags:
        - Bundesliga
      parameters:
        - name: match_id
          in: query
          required: true
          schema:
            type: integer
          description: The match ID to retrieve player props for (required)
      responses:
        "200":
          description: Bundesliga player prop betting odds
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerPlayerProp"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /bundesliga/v1/odds/player_props/opening:
    get:
      summary: Get Bundesliga 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:
        - Bundesliga
      parameters:
        - name: match_id
          in: query
          required: true
          schema:
            type: integer
          description: The match 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:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerOpeningPlayerProp"
                  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"

  /bundesliga/v1/match_shots:
    get:
      summary: Get Bundesliga match shots
      description: |
        Retrieve shot-map entries with expected goals (xG / xGoT) and pitch
        coordinates. Available for matches in the current and future seasons
        only; older matches return empty results. Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Match shot entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchShot"
                  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"
  /bundesliga/v1/match_momentum:
    get:
      summary: Get Bundesliga match attack momentum
      description: |
        Retrieve per-minute attack momentum values. Positive values favor the
        home side, negative values favor the away side. Available for matches
        in the current and future seasons only. Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Per-minute momentum points
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchMomentumPoint"
                  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"
  /bundesliga/v1/match_best_players:
    get:
      summary: Get Bundesliga match top performers
      description: |
        Retrieve the top-rated players for each match (best XI per side and
        the man of the match). Available for matches in the current and
        future seasons only. Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Match best player entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchBestPlayer"
                  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"
  /bundesliga/v1/match_avg_positions:
    get:
      summary: Get Bundesliga player average positions
      description: |
        Retrieve each player's average pitch position (heatmap centroid) for
        a match. Coordinates are normalized 0-100. Available for matches in
        the current and future seasons only. Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: team_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Player average position entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchAvgPosition"
                  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"
  /bundesliga/v1/match_heatmaps:
    get:
      summary: Get Bundesliga player heatmaps
      description: |
        Retrieve per-player heatmap dots for a match. Heatmap data is
        published only after a match concludes; in-progress matches return
        zero heatmap rows, with data landing within ~20 minutes of full-time.
        Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - name: player_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Per-player heatmap entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchHeatmap"
                  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"
  /bundesliga/v1/match_pregame_forms:
    get:
      summary: Get Bundesliga pre-match team form
      description: |
        Retrieve a pre-match team-form summary for each side - recent
        average rating, league position entering the match, and a list of
        the team's most-recent results. Available for matches in the current
        and future seasons only. Requires GOAT tier.
      tags:
        - Bundesliga
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: match_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: Pre-match team form entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/SoccerMatchPregameForm"
                  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"