openapi: 3.1.0
info:
  title: BALLDONTLIE - Serie A API
  version: 1.0.0
  description: Serie A 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
    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:
  /seriea/v1/teams:
    get:
      summary: Get Serie A teams
      description: Get all teams participating in Serie A for a given season
      tags:
        - Serie A
      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 Serie A 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"
  /seriea/v1/rosters:
    get:
      summary: Get Serie A team rosters
      description: Get player roster information for a specific team and season
      tags:
        - Serie A
      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"
  /seriea/v1/players:
    get:
      summary: Get Serie A players
      description: Get players with optional filtering by team or search term. Supports pagination.
      tags:
        - Serie A
      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 Serie A 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"
  /seriea/v1/player_injuries:
    get:
      summary: Get Serie A player injuries
      description: Retrieve the current Serie A player injury snapshot. Supports filtering by player IDs, team IDs, or injury status. Requires GOAT tier access.
      tags:
        - Serie A
      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 Serie A 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"
  /seriea/v1/standings:
    get:
      summary: Get Serie A standings
      description: Get league standings for a specific season
      tags:
        - Serie A
      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"
  /seriea/v1/matches:
    get:
      summary: Get Serie A matches
      description: Get matches with optional filtering by season, dates, or teams. Supports pagination.
      tags:
        - Serie A
      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"
  /seriea/v1/match_events:
    get:
      summary: Get Serie A match events
      description: Get match events (goals, cards, substitutions, etc.) with optional filtering by matches. Supports pagination.
      tags:
        - Serie A
      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"
  /seriea/v1/match_lineups:
    get:
      summary: Get Serie A match lineups
      description: Get match lineups (starting and substitute players) with optional filtering by matches. Supports pagination.
      tags:
        - Serie A
      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"
  /seriea/v1/player_match_stats:
    get:
      summary: Get Serie A player match statistics
      description: Get player match statistics with optional filtering by matches or players. Supports pagination.
      tags:
        - Serie A
      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"
  /seriea/v1/team_match_stats:
    get:
      summary: Get Serie A team match statistics
      description: Get team match statistics with optional filtering by matches or teams. Supports pagination.
      tags:
        - Serie A
      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"
  /seriea/v1/odds:
    get:
      summary: Get Serie A betting odds
      description: Retrieve betting odds for Serie A matches. Supports filtering by match IDs or dates. Serie A odds include moneyline odds for home, away, and draw outcomes only (no spreads or totals). Supports pagination.
      tags:
        - Serie A
      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: Serie A 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"
  /seriea/v1/odds/player_props:
    get:
      summary: Get Serie A player prop betting odds
      description: |
        Retrieve live player prop betting data for Serie A 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:
        - Serie A
      parameters:
        - name: match_id
          in: query
          required: true
          schema:
            type: integer
          description: The match ID to retrieve player props for (required)
      responses:
        "200":
          description: Serie A 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"
  /seriea/v1/match_shots:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"
  /seriea/v1/match_momentum:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"
  /seriea/v1/match_best_players:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"
  /seriea/v1/match_avg_positions:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"
  /seriea/v1/match_heatmaps:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"
  /seriea/v1/match_pregame_forms:
    get:
      summary: Get Serie A 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:
        - Serie A
      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"