openapi: 3.1.0
info:
  title: BALLDONTLIE - League of Legends API
  version: 1.0.0
  description: League of Legends 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
    LOLChampion:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    LOLChampionStats:
      type: object
      properties:
        id:
          type: integer
        champion:
          $ref: "#/components/schemas/LOLChampion"
        games_count:
          type: integer
        picks_count:
          type: integer
        picks_rate:
          type: number
        wins_count:
          type: integer
        loses_count:
          type: integer
        win_rate:
          type: number
        ban_rate:
          type: number
        avg_kills:
          type: number
        avg_deaths:
          type: number
        avg_assists:
          type: number
        kda:
          type: number
        kp:
          type: number
          description: Kill participation rate
        avg_damage_dealt_to_champions:
          type: number
        avg_gold_earned:
          type: number
        avg_gold_per_min:
          type: number
        avg_creep_score:
          type: number
    LOLItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        is_trinket:
          type: boolean
    LOLMatch:
      type: object
      properties:
        id:
          type: integer
        slug:
          type: string
          nullable: true
        tournament:
          $ref: "#/components/schemas/LOLTournament"
        team1:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
        team2:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
        winner:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
        team1_score:
          type: integer
          nullable: true
        team2_score:
          type: integer
          nullable: true
        bo_type:
          type: integer
          nullable: true
          description: Best of type (1, 3, 5)
        status:
          type: string
          nullable: true
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
    LOLMatchMap:
      type: object
      properties:
        id:
          type: integer
        match_id:
          type: integer
        game_number:
          type: integer
          nullable: true
        winner:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
        loser:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
        duration:
          type: integer
          nullable: true
        status:
          type: string
          nullable: true
        begin_at:
          type: string
          format: date-time
          nullable: true
        end_at:
          type: string
          format: date-time
          nullable: true
    LOLPlayer:
      type: object
      properties:
        id:
          type: integer
        nickname:
          type: string
        slug:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        birthday:
          type: string
          format: date
          nullable: true
        country:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        team:
          $ref: "#/components/schemas/LOLTeamSlim"
          nullable: true
    LOLPlayerMatchMapStat:
      type: object
      properties:
        id:
          type: integer
        match_map_id:
          type: integer
        player:
          $ref: "#/components/schemas/LOLPlayerSlim"
        team:
          $ref: "#/components/schemas/LOLTeamSlim"
        champion:
          $ref: "#/components/schemas/LOLChampion"
        role:
          type: string
          nullable: true
        level:
          type: integer
        kills:
          type: integer
        deaths:
          type: integer
        assists:
          type: integer
        kill_participation:
          type: number
        creep_score:
          type: integer
        gold_earned:
          type: integer
        gold_per_min:
          type: number
        total_damage_dealt_to_champions:
          type: integer
        wards_placed:
          type: integer
        kills_wards:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/LOLItem"
        spells:
          type: array
          items:
            $ref: "#/components/schemas/LOLSpell"
        runes:
          type: array
          items:
            type: object
            properties:
              rune_path:
                $ref: "#/components/schemas/LOLRunePath"
                nullable: true
              keystone:
                $ref: "#/components/schemas/LOLRune"
                nullable: true
              path_type:
                type: integer
    LOLPlayerOverallStat:
      type: object
      properties:
        id:
          type: integer
        player:
          $ref: "#/components/schemas/LOLPlayerSlim"
        maps_played:
          type: integer
        total_kills:
          type: integer
        avg_kills:
          type: number
        total_deaths:
          type: integer
        avg_deaths:
          type: number
        total_assists:
          type: integer
        avg_assists:
          type: number
        kp:
          type: number
          description: Kill participation rate
        total_damage:
          type: integer
        avg_damage:
          type: number
        avg_gold_per_min:
          type: number
        avg_creep_score:
          type: number
    LOLPlayerSlim:
      type: object
      properties:
        id:
          type: integer
        nickname:
          type: string
          nullable: true
    LOLRegion:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Region name (e.g., North America, Europe)
    LOLRune:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        rune_path:
          $ref: "#/components/schemas/LOLRunePath"
          nullable: true
        rune_type:
          type: string
          description: Rune type (keystone, slot1, slot2, slot3, shard)
    LOLRunePath:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    LOLSpell:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    LOLTeam:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        region:
          $ref: "#/components/schemas/LOLRegion"
          nullable: true
    LOLTeamMatchMapStat:
      type: object
      properties:
        id:
          type: integer
        match_map_id:
          type: integer
        team:
          $ref: "#/components/schemas/LOLTeamSlim"
        enemy_team:
          $ref: "#/components/schemas/LOLTeamSlim"
        side:
          type: integer
        color:
          type: string
          nullable: true
        kills:
          type: integer
        deaths:
          type: integer
        assists:
          type: integer
        creep_score:
          type: integer
        gold_earned:
          type: integer
        total_damage_dealt_to_champions:
          type: integer
        baron_kills:
          type: integer
        dragon_kills:
          type: integer
        herald_kills:
          type: integer
        first_blood:
          type: integer
        first_tower:
          type: integer
        first_baron:
          type: integer
        first_dragon:
          type: integer
    LOLTeamSlim:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    LOLTournament:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
          nullable: true
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
        prize:
          type: integer
          nullable: true
        tier:
          type: string
          nullable: true
          description: Tournament tier (s, a, b, c)
        status:
          type: string
          nullable: true
    LOLTournamentRoster:
      type: object
      properties:
        tournament_id:
          type: integer
        team_id:
          type: integer
        player:
          $ref: "#/components/schemas/LOLPlayerSlim"
    LOLTournamentTeam:
      type: object
      properties:
        tournament_id:
          type: integer
        team:
          $ref: "#/components/schemas/LOLTeamSlim"
    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
  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:
  /lol/v1/teams:
    get:
      summary: Get all LOL teams
      description: Retrieve a list of all professional League of Legends teams
      tags:
        - LOL
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search teams by name
      responses:
        "200":
          description: List of LOL teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLTeam"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/players:
    get:
      summary: Get all LOL players
      description: Retrieve a list of all professional League of Legends players
      tags:
        - LOL
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search players by nickname or name
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
      responses:
        "200":
          description: List of LOL players
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLPlayer"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/champions:
    get:
      summary: Get all LOL champions
      description: Retrieve a list of all League of Legends champions
      tags:
        - LOL
      responses:
        "200":
          description: List of LOL champions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLChampion"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/items:
    get:
      summary: Get all LOL items
      description: Retrieve a list of all League of Legends in-game items
      tags:
        - LOL
      responses:
        "200":
          description: List of LOL items
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLItem"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/spells:
    get:
      summary: Get all LOL summoner spells
      description: Retrieve a list of all League of Legends summoner spells
      tags:
        - LOL
      responses:
        "200":
          description: List of LOL summoner spells
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLSpell"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/rune_paths:
    get:
      summary: Get all LOL rune paths
      description: Retrieve a list of all League of Legends rune paths (Domination, Inspiration, Precision, Resolve, Sorcery)
      tags:
        - LOL
      responses:
        "200":
          description: List of LOL rune paths
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLRunePath"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/runes:
    get:
      summary: Get all LOL runes
      description: Retrieve a list of all League of Legends runes with their paths and types
      tags:
        - LOL
      responses:
        "200":
          description: List of LOL runes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLRune"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/tournaments:
    get:
      summary: Get LOL tournaments
      description: Retrieve a list of professional League of Legends tournaments. Requires ALL-STAR tier or higher.
      tags:
        - LOL
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: List of LOL tournaments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLTournament"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/tournament_teams:
    get:
      summary: Get teams in a tournament
      description: Retrieve teams participating in a specific tournament. Requires ALL-STAR tier or higher.
      tags:
        - LOL
      parameters:
        - name: tournament_id
          in: query
          required: true
          schema:
            type: integer
          description: Tournament ID
      responses:
        "200":
          description: List of teams in tournament
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLTournamentTeam"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/tournament_roster:
    get:
      summary: Get tournament roster
      description: Retrieve player rosters for a tournament and team. Requires ALL-STAR tier or higher.
      tags:
        - LOL
      parameters:
        - name: tournament_id
          in: query
          required: true
          schema:
            type: integer
          description: Tournament ID
        - name: team_id
          in: query
          required: true
          schema:
            type: integer
          description: Team ID
      responses:
        "200":
          description: Tournament roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLTournamentRoster"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/champion_stats:
    get:
      summary: Get champion statistics
      description: Retrieve aggregate statistics for LOL champions across professional matches. Requires ALL-STAR tier or higher.
      tags:
        - LOL
      responses:
        "200":
          description: Champion statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLChampionStats"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/matches:
    get:
      summary: Get LOL matches
      description: Retrieve professional League of Legends matches. Requires GOAT tier.
      tags:
        - LOL
      parameters:
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
        - name: tournament_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by tournament ID
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
      responses:
        "200":
          description: List of LOL matches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLMatch"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/match_maps:
    get:
      summary: Get match maps (games)
      description: Retrieve individual games within a match. Requires GOAT tier.
      tags:
        - LOL
      parameters:
        - name: match_id
          in: query
          required: true
          schema:
            type: integer
          description: Match ID to get games for
      responses:
        "200":
          description: List of match maps
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLMatchMap"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/player_match_map_stats:
    get:
      summary: Get player match map statistics
      description: Retrieve detailed player statistics for individual games. Requires GOAT tier.
      tags:
        - LOL
      parameters:
        - name: match_map_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by match map ID
        - name: player_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by player ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Player match map statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLPlayerMatchMapStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/team_match_map_stats:
    get:
      summary: Get team match map statistics
      description: Retrieve detailed team statistics for individual games. Requires GOAT tier.
      tags:
        - LOL
      parameters:
        - name: match_map_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by match map ID
        - name: team_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by team ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Team match map statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLTeamMatchMapStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"
  /lol/v1/player_overall_stats:
    get:
      summary: Get player overall statistics
      description: Retrieve career statistics for LOL players. Requires GOAT tier.
      tags:
        - LOL
      parameters:
        - name: player_id
          in: query
          required: false
          schema:
            type: integer
          description: Filter by player ID
        - $ref: "#/components/parameters/CursorParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Player overall statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/LOLPlayerOverallStat"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/ServerError"