Skip to main content
GET
/
api
/
tv
/
channels
Get Current TV Channels
curl --request GET \
  --url https://api.example.com/api/tv/channels
{
  "[channelKey]": {
    "user": {
      "id": "<string>",
      "name": "<string>",
      "title": "<string>"
    },
    "rating": 123,
    "gameId": "<string>",
    "color": "<string>"
  }
}

​
Overview

This endpoint returns information about the current champion game for each TV channel on Lichess. TV channels feature ongoing games filtered by different criteria such as rating level, time control, or chess variant.

​
Endpoint

GET https://lichess.org/api/tv/channels

​
Authentication

No authentication required. This is a public endpoint.

​
Request

No parameters required.

​
Example Request

cURL
curl https://lichess.org/api/tv/channels
JavaScript
fetch('https://lichess.org/api/tv/channels')
  .then(response => response.json())
  .then(data => console.log(data));
Python
import requests

response = requests.get('https://lichess.org/api/tv/channels')
channels = response.json()
print(channels)

​
Response

Returns a JSON object where each key is a channel name and the value contains information about the current featured game and player.

​
Response Fields

​
[channelKey]
object
Each channel key (e.g., “best”, “bullet”, “blitz”) contains a champion object

​
Available Channels

Lichess TV features the following channels:
  • best: Top Rated - Highest rated standard chess games (2150+ rating)
  • bullet: Bullet games (less than 3 minutes)
  • blitz: Blitz games (3-8 minutes)
  • rapid: Rapid games (8-25 minutes)
  • classical: Classical games (25+ minutes)
  • chess960: Chess960 variant games
  • kingOfTheHill: King of the Hill variant
  • threeCheck: Three-check variant
  • antichess: Antichess variant
  • atomic: Atomic variant
  • horde: Horde variant
  • racingKings: Racing Kings variant
  • crazyhouse: Crazyhouse variant
  • ultraBullet: UltraBullet games (less than 30 seconds)
  • bot: Games involving bots
  • computer: Games against computer (AI)

​
Example Response

{
  "best": {
    "user": {
      "id": "magnus",
      "name": "Magnus",
      "title": "GM"
    },
    "rating": 2847,
    "gameId": "q7ZvsdUF",
    "color": "white"
  },
  "bullet": {
    "user": {
      "id": "hikaru",
      "name": "Hikaru",
      "title": "GM"
    },
    "rating": 3201,
    "gameId": "8ZhJgF3b",
    "color": "black"
  },
  "blitz": {
    "user": {
      "id": "danya",
      "name": "Danya"
    },
    "rating": 2963,
    "gameId": "z6brKWaG",
    "color": "white"
  }
}

​
Rate Limiting

This endpoint follows standard Lichess API rate limits. Excessive polling is discouraged.

​
Notes

  • The champions and games update automatically as new games become available
  • Not all channels may have active games at all times
  • Games must be rated and meet minimum rating requirements for most channels
  • Games are selected based on recency - they must have had a move recently to remain featured

​
Source Code Reference

  • Controller: app/controllers/Tv.scala:30 (channels method)
  • Model: modules/tv/src/main/Tv.scala:64-66 (Champion case class)
  • Routes: conf/routes:42 (GET /api/tv/channels)

Build docs developers (and LLMs) love

Get started for freeTalk to us