Introduction
The Agent LoL API provides programmatic access to League of Legends match data, player statistics, and AI-powered coaching insights. Built on top of the Riot Games API, it offers authenticated endpoints for retrieving account information, match history, detailed match data, and timeline analysis.Authentication
All API endpoints require authentication via NextAuth session. The API uses thegetRiotSessionOrFail helper to validate:
- Active user session
- Valid Riot API key
- User PUUID (Player Universally Unique Identifier)
401 Unauthorized response.
Base URL
Rate Limiting
The API is subject to Riot Games API rate limits:- Rate limits vary by endpoint and API key tier
- Default caching is disabled (
cache: 'no-store') for real-time data - Consider implementing client-side caching for frequently accessed data
Error Handling
All endpoints follow a consistent error response pattern:Available Endpoints
Account Management
Get PUUID
Retrieve current user’s PUUID and Riot ID
Get Riot ID
Fetch Riot ID details by PUUID
Match Data
Match IDs
Get list of match IDs for a player
Match Details
Retrieve detailed match information with AI context
Timeline Analysis
Match Timeline
Get frame-by-frame match timeline data
AI Comparison
Compare player performance with AI coaching insights
Data Dragon
Get Version
Retrieve the latest Data Dragon version for champion assets
Data Dragon Version
Retrieves the latest Data Dragon version number from Riot’s CDN. This version is used to construct URLs for champion icons, item images, and other game assets.Authentication
Does not require authentication. This endpoint is publicly accessible.Response
The latest Data Dragon version (e.g., “14.1.1”)
Example
This endpoint caches the version for 1 hour to reduce load on Riot’s Data Dragon API.
AI Features
Agent LoL includes optional AI-powered features when enabled:Enable AI coaching features for match analysis
OpenAI API key for AI analysis features
analysis or comparison fields with AI-generated coaching insights.
Response Formats
All successful responses return JSON data. Response schemas are documented on individual endpoint pages.Getting Started
- Authenticate with NextAuth
- Retrieve your PUUID from
/api/riot/account/get-puuid - Fetch match IDs from
/api/riot/match/by-puuid/ids - Get detailed match data from
/api/riot/match/matchId - Analyze timeline data with
/api/riot/match/timeline/compare