openapi: 3.0.3
info:
  title: Riot Games League of Legends API
  description: >-
    The Riot Games Developer API provides access to League of Legends game data
    including summoner profiles, champion mastery, ranked standings, match
    history, live spectator data, and tournament management. API keys are
    obtained through the Riot Developer Portal.
  version: v4/v5
  contact:
    name: Riot Developer Portal
    url: https://developer.riotgames.com/
  termsOfService: https://developer.riotgames.com/policies/general
servers:
  - url: https://na1.api.riotgames.com
    description: North America
  - url: https://euw1.api.riotgames.com
    description: Europe West
  - url: https://kr.api.riotgames.com
    description: Korea
  - url: https://americas.api.riotgames.com
    description: Americas (for account/match endpoints)
tags:
  - name: Summoner
    description: Summoner profile operations
  - name: Champion Mastery
    description: Champion mastery data
  - name: League
    description: Ranked league standings
  - name: Match
    description: Match history and details
  - name: Spectator
    description: Live game spectator data
  - name: Clash
    description: Clash tournament operations
  - name: Champion
    description: Free champion rotation
  - name: Status
    description: Platform status
paths:
  /lol/summoner/v4/summoners/by-name/{summonerName}:
    get:
      operationId: getSummonerByName
      summary: Get Summoner By Name
      description: Get a summoner by summoner name. Deprecated - use Riot ID instead.
      tags:
        - Summoner
      parameters:
        - name: summonerName
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Summoner data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummonerDTO'
        '403':
          description: Forbidden
        '404':
          description: Not found
  /lol/summoner/v4/summoners/by-puuid/{encryptedPUUID}:
    get:
      operationId: getSummonerByPUUID
      summary: Get Summoner By PUUID
      description: Get a summoner by PUUID.
      tags:
        - Summoner
      parameters:
        - name: encryptedPUUID
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Summoner data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummonerDTO'
  /lol/summoner/v4/summoners/{encryptedSummonerId}:
    get:
      operationId: getSummonerById
      summary: Get Summoner By ID
      description: Get a summoner by encrypted summoner ID.
      tags:
        - Summoner
      parameters:
        - name: encryptedSummonerId
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Summoner data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummonerDTO'
  /lol/champion-mastery/v4/champion-masteries/by-puuid/{encryptedPUUID}:
    get:
      operationId: getChampionMasteryByPUUID
      summary: Get Champion Mastery By PUUID
      description: Get all champion mastery entries sorted by number of champion points descending.
      tags:
        - Champion Mastery
      parameters:
        - name: encryptedPUUID
          in: path
          required: true
          schema:
            type: string
        - name: count
          in: query
          description: Number of champion mastery entries to return
          schema:
            type: integer
      security:
        - ApiKey: []
      responses:
        '200':
          description: Champion mastery list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChampionMasteryDTO'
  /lol/champion-mastery/v4/champion-masteries/by-puuid/{encryptedPUUID}/by-champion/{championId}:
    get:
      operationId: getChampionMasteryByPUUIDAndChampion
      summary: Get Champion Mastery By PUUID And Champion
      description: Get a champion mastery by PUUID and champion ID.
      tags:
        - Champion Mastery
      parameters:
        - name: encryptedPUUID
          in: path
          required: true
          schema:
            type: string
        - name: championId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      security:
        - ApiKey: []
      responses:
        '200':
          description: Champion mastery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChampionMasteryDTO'
  /lol/league/v4/entries/by-summoner/{encryptedSummonerId}:
    get:
      operationId: getLeagueEntriesBySummoner
      summary: Get League Entries By Summoner
      description: Get league entries in all queues for a given summoner ID.
      tags:
        - League
      parameters:
        - name: encryptedSummonerId
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: League entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LeagueEntryDTO'
  /lol/league/v4/entries/{queue}/{tier}/{division}:
    get:
      operationId: getLeagueEntries
      summary: Get League Entries
      description: Get all the league entries for a given queue, tier, and division.
      tags:
        - League
      parameters:
        - name: queue
          in: path
          required: true
          description: Queue type (e.g., RANKED_SOLO_5x5)
          schema:
            type: string
        - name: tier
          in: path
          required: true
          description: Tier (e.g., GOLD)
          schema:
            type: string
        - name: division
          in: path
          required: true
          description: Division (e.g., I)
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      security:
        - ApiKey: []
      responses:
        '200':
          description: League entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LeagueEntryDTO'
  /lol/league/v4/challengerleagues/by-queue/{queue}:
    get:
      operationId: getChallengerLeague
      summary: Get Challenger League
      description: Get the challenger league for a given queue.
      tags:
        - League
      parameters:
        - name: queue
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Challenger league
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeagueListDTO'
  /lol/match/v5/matches/by-puuid/{puuid}/ids:
    get:
      operationId: getMatchIdsByPUUID
      summary: Get Match IDs By PUUID
      description: Get a list of match IDs by PUUID.
      tags:
        - Match
      parameters:
        - name: puuid
          in: path
          required: true
          schema:
            type: string
        - name: queue
          in: query
          description: Filter by queue ID
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by game type
          schema:
            type: string
        - name: start
          in: query
          description: Start index for pagination
          schema:
            type: integer
            default: 0
        - name: count
          in: query
          description: Number of match IDs to return (max 100)
          schema:
            type: integer
            default: 20
            maximum: 100
      security:
        - ApiKey: []
      responses:
        '200':
          description: List of match IDs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /lol/match/v5/matches/{matchId}:
    get:
      operationId: getMatch
      summary: Get Match
      description: Get match by match ID.
      tags:
        - Match
      parameters:
        - name: matchId
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Match data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchDTO'
  /lol/match/v5/matches/{matchId}/timeline:
    get:
      operationId: getMatchTimeline
      summary: Get Match Timeline
      description: Get match timeline by match ID.
      tags:
        - Match
      parameters:
        - name: matchId
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Match timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchTimelineDTO'
  /lol/spectator/v5/active-games/by-summoner/{encryptedSummonerId}:
    get:
      operationId: getLiveGame
      summary: Get Live Game
      description: Get current game information for the given summoner ID.
      tags:
        - Spectator
      parameters:
        - name: encryptedSummonerId
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Current game info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentGameInfoDTO'
        '404':
          description: No live game found
  /lol/spectator/v5/featured-games:
    get:
      operationId: getFeaturedGames
      summary: Get Featured Games
      description: Get list of featured games.
      tags:
        - Spectator
      security:
        - ApiKey: []
      responses:
        '200':
          description: Featured games list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturedGamesDTO'
  /lol/clash/v1/players/by-puuid/{puuid}:
    get:
      operationId: getClashPlayersByPUUID
      summary: Get Clash Players By PUUID
      description: Get players in Clash by PUUID.
      tags:
        - Clash
      parameters:
        - name: puuid
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Clash player list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClashPlayerDTO'
  /lol/champion/v3/champion-rotations:
    get:
      operationId: getChampionRotations
      summary: Get Champion Rotations
      description: Get the current free champion rotation and weekly free champion rotation.
      tags:
        - Champion
      security:
        - ApiKey: []
      responses:
        '200':
          description: Champion rotation data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChampionInfoDTO'
  /lol/status/v4/platform-data:
    get:
      operationId: getPlatformStatus
      summary: Get Platform Status
      description: Get League of Legends platform status.
      tags:
        - Status
      security:
        - ApiKey: []
      responses:
        '200':
          description: Platform status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformDataDTO'
  /riot/account/v1/accounts/by-riot-id/{gameName}/{tagLine}:
    get:
      operationId: getAccountByRiotId
      summary: Get Account By Riot ID
      description: Get account by Riot ID (gameName + tagLine). Returns PUUID for use in other APIs.
      tags:
        - Summoner
      parameters:
        - name: gameName
          in: path
          required: true
          schema:
            type: string
        - name: tagLine
          in: path
          required: true
          schema:
            type: string
      security:
        - ApiKey: []
      responses:
        '200':
          description: Account data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDTO'
        '404':
          description: Account not found
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Riot-Token
  schemas:
    SummonerDTO:
      type: object
      properties:
        id:
          type: string
          description: Encrypted summoner ID
        accountId:
          type: string
          description: Encrypted account ID
        puuid:
          type: string
          description: Encrypted PUUID
        name:
          type: string
          description: Summoner name (deprecated)
        profileIconId:
          type: integer
        revisionDate:
          type: integer
          format: int64
        summonerLevel:
          type: integer
          format: int64
    ChampionMasteryDTO:
      type: object
      properties:
        puuid:
          type: string
        championId:
          type: integer
          format: int64
        championLevel:
          type: integer
        championPoints:
          type: integer
          format: int64
        lastPlayTime:
          type: integer
          format: int64
        championPointsSinceLastLevel:
          type: integer
          format: int64
        championPointsUntilNextLevel:
          type: integer
          format: int64
        chestGranted:
          type: boolean
        tokensEarned:
          type: integer
    LeagueEntryDTO:
      type: object
      properties:
        leagueId:
          type: string
        summonerId:
          type: string
        summonerName:
          type: string
        queueType:
          type: string
        tier:
          type: string
        rank:
          type: string
        leaguePoints:
          type: integer
        wins:
          type: integer
        losses:
          type: integer
        hotStreak:
          type: boolean
        veteran:
          type: boolean
        freshBlood:
          type: boolean
        inactive:
          type: boolean
    LeagueListDTO:
      type: object
      properties:
        leagueId:
          type: string
        entries:
          type: array
          items:
            $ref: '#/components/schemas/LeagueEntryDTO'
        tier:
          type: string
        name:
          type: string
        queue:
          type: string
    MatchDTO:
      type: object
      properties:
        metadata:
          type: object
          properties:
            dataVersion:
              type: string
            matchId:
              type: string
            participants:
              type: array
              items:
                type: string
        info:
          type: object
          properties:
            gameCreation:
              type: integer
              format: int64
            gameDuration:
              type: integer
              format: int64
            gameId:
              type: integer
              format: int64
            gameMode:
              type: string
            gameName:
              type: string
            gameType:
              type: string
            gameVersion:
              type: string
            mapId:
              type: integer
            participants:
              type: array
              items:
                $ref: '#/components/schemas/ParticipantDTO'
            platformId:
              type: string
            queueId:
              type: integer
            teams:
              type: array
              items:
                type: object
    MatchTimelineDTO:
      type: object
      properties:
        metadata:
          type: object
          properties:
            matchId:
              type: string
        info:
          type: object
          properties:
            frameInterval:
              type: integer
            frames:
              type: array
              items:
                type: object
    ParticipantDTO:
      type: object
      properties:
        puuid:
          type: string
        summonerName:
          type: string
        championId:
          type: integer
        championName:
          type: string
        kills:
          type: integer
        deaths:
          type: integer
        assists:
          type: integer
        totalDamageDealt:
          type: integer
          format: int64
        goldEarned:
          type: integer
        win:
          type: boolean
        teamId:
          type: integer
        teamPosition:
          type: string
    CurrentGameInfoDTO:
      type: object
      properties:
        gameId:
          type: integer
          format: int64
        gameType:
          type: string
        gameStartTime:
          type: integer
          format: int64
        mapId:
          type: integer
          format: int64
        gameLength:
          type: integer
          format: int64
        platformId:
          type: string
        gameMode:
          type: string
        gameQueueConfigId:
          type: integer
          format: int64
        participants:
          type: array
          items:
            $ref: '#/components/schemas/CurrentGameParticipantDTO'
    CurrentGameParticipantDTO:
      type: object
      properties:
        teamId:
          type: integer
          format: int64
        spell1Id:
          type: integer
          format: int64
        spell2Id:
          type: integer
          format: int64
        championId:
          type: integer
          format: int64
        profileIconId:
          type: integer
          format: int64
        summonerName:
          type: string
        puuid:
          type: string
    FeaturedGamesDTO:
      type: object
      properties:
        gameList:
          type: array
          items:
            $ref: '#/components/schemas/CurrentGameInfoDTO'
        clientRefreshInterval:
          type: integer
          format: int64
    ClashPlayerDTO:
      type: object
      properties:
        summonerId:
          type: string
        teamId:
          type: string
        position:
          type: string
        role:
          type: string
    ChampionInfoDTO:
      type: object
      properties:
        freeChampionIds:
          type: array
          items:
            type: integer
        freeChampionIdsForNewPlayers:
          type: array
          items:
            type: integer
        maxNewPlayerLevel:
          type: integer
    PlatformDataDTO:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        locales:
          type: array
          items:
            type: string
        maintenances:
          type: array
          items:
            type: object
        incidents:
          type: array
          items:
            type: object
    AccountDTO:
      type: object
      properties:
        puuid:
          type: string
          description: Encrypted PUUID for use in game-specific APIs
        gameName:
          type: string
        tagLine:
          type: string