logo
API docs by Redocly

Lichess.org API reference (2.0.0)

Download OpenAPI specification:Download

Lichess.org API: contact@lichess.org URL: https://lichess.org/api License: AGPL-3.0-or-later

Introduction

Welcome to the reference for the Lichess API! Lichess is free/libre, open-source chess server powered by volunteers and donations.

Endpoint

All requests go to https://lichess.org (unless otherwise specified).

Rate limiting

All requests are rate limited using various strategies, to ensure the API remains responsive for everyone. Only make one request at a time. If you receive an HTTP response with a 429 status, please wait a full minute before resuming API usage.

Streaming with ND-JSON

Some API endpoints stream their responses as Newline Delimited JSON a.k.a. nd-json, with one JSON object per line.

Here's a JavaScript utility function to help reading NDJSON streamed responses.

Authentication

Which authentication method is right for me?

Read about the Lichess API authentication methods and code examples

Personal Access Token

Personal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.

Token Security

  • Keep your tokens secret. Do not share them in public repositories or public forums.
  • Your tokens can be used to make your account perform arbitrary actions (within the limits of the tokens' scope). You remain responsible for all activities on your account.
  • Do not hardcode tokens in your application's code. Use environment variables or a secure storage and ensure they are not shipped/exposed to users. Be especially careful that they are not included in frontend bundles or apps that are shipped to users.
  • If you suspect a token has been compromised, revoke it immediately.

To see your active tokens or revoke them, see your Personal API access tokens.

Authorization Code Flow with PKCE

The authorization code flow with PKCE allows your users to login with Lichess. Lichess supports unregistered and public clients (no client authentication, choose any unique client id). The only accepted code challenge method is S256. Access tokens are long-lived (expect one year), unless they are revoked. Refresh tokens are not supported.

See the documentation for the OAuth endpoints or the PKCE RFC for a precise protocol description.

Real life examples

Token format

Access tokens and authorization codes match ^[A-Za-z0-9_]+$. The length of tokens can be increased without notice. Make sure your application can handle at least 512 characters. By convention tokens have a recognizable prefix, but do not rely on this.

Account

Read and write account information and preferences. https://lichess.org/account/preferences/game-display

Get my profile

Public information about the logged in user.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "id": "georges",
  • "username": "Georges",
  • "perfs": {
    },
  • "flair": "string",
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "verified": true,
  • "playTime": {
    },
  • "title": "NM",
  • "url": "https://lichess.org/@/georges",
  • "playing": "https://lichess.org/yqfLYJ5E/black",
  • "count": {
    },
  • "streaming": false,
  • "streamer": {},
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Get my email address

Read the email address of the logged in user.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "email": "abathur@mail.org"
}

Get my preferences

Read the preferences of the logged in user.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "prefs": {
    },
  • "language": "en-US"
}

Get my kid mode status

Read the kid mode status of the logged in user.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "kid": false
}

Set my kid mode status

Set the kid mode status of the logged in user.

Authorizations:
OAuth2
query Parameters
v
required
boolean
Example: v=true

Kid mode status

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get my timeline

Get the timeline events of the logged in user.

Authorizations:
OAuth2
query Parameters
since
integer >= 1356998400070

Show events since this timestamp.

nb
integer [ 1 .. 30 ]
Default: 15

Max number of events to fetch.

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "users": {
    }
}

Users

Access registered users on Lichess. https://lichess.org/player

Get real-time users status

Read the online, playing and streaming flags of several users. This API is very fast and cheap on lichess side. So you can call it quite often (like once every 5 seconds). Use it to track players and know when they're connected on lichess and playing games.

query Parameters
ids
required
string
Example: ids=thibault,maia1,maia5

User IDs separated by commas. Up to 100 IDs.

withSignal
boolean
Example: withSignal=true

Also return the network signal of the player, when available. It ranges from 1 (poor connection, lag > 500ms) to 4 (great connection, lag < 150ms) Defaults to false to preserve server resources.

withGameIds
boolean
Example: withGameIds=true

Also return the ID of the game being played, if any, for each player, in a playingId field. Defaults to false to preserve server resources.

withGameMetas
boolean
Example: withGameMetas=true

Also return the id, time control and variant of the game being played, if any, for each player, in a playing field. Defaults to false to preserve server resources. Disables withGameIds.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get all top 10

Get the top 10 players for each speed and variant. See https://lichess.org/player.

Responses

Response samples

Content type
application/json
{
  • "bullet": [
    ],
  • "blitz": [ ],
  • "rapid": [ ],
  • "classical": [ ],
  • "ultraBullet": [ ],
  • "chess960": [ ],
  • "crazyhouse": [ ],
  • "antichess": [ ],
  • "atomic": [ ],
  • "horde": [ ],
  • "kingOfTheHill": [ ],
  • "racingKings": [ ],
  • "threeCheck": [ ]
}

Get one leaderboard

Get the leaderboard for a single speed or variant (a.k.a. perfType). There is no leaderboard for correspondence or puzzles. See https://lichess.org/player/top/200/bullet.

path Parameters
nb
required
integer [ 1 .. 200 ]
Example: 100

How many users to fetch

perfType
required
string
Enum: "ultraBullet" "bullet" "blitz" "rapid" "classical" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"
Example: bullet

The speed or variant

Responses

Response samples

Content type
application/vnd.lichess.v3+json
{
  • "users": [
    ]
}

Get user public data

Read public data of a user.

Authorizations:
OAuth2
path Parameters
username
required
string
query Parameters
trophies
boolean
Default: false

Include user trophies

Responses

Response samples

Content type
application/json
{
  • "id": "georges",
  • "username": "Georges",
  • "perfs": {
    },
  • "flair": "string",
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "verified": true,
  • "playTime": {
    },
  • "title": "NM",
  • "url": "https://lichess.org/@/georges",
  • "playing": "https://lichess.org/yqfLYJ5E/black",
  • "count": {
    },
  • "streaming": false,
  • "streamer": {},
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Get rating history of a user

Read rating history of a user, for all perf types. There is at most one entry per day. Format of an entry is [year, month, day, rating]. month starts at zero (January).

path Parameters
username
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get performance statistics of a user

Read performance statistics of a user, for a single performance. Similar to the performance pages on the website.

path Parameters
username
required
string
perf
required
string (PerfType)
Enum: "ultraBullet" "bullet" "blitz" "rapid" "classical" "correspondence" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "perf": {
    },
  • "rank": 98121,
  • "percentile": 69.7,
  • "stat": {
    }
}

Get user activity

Read data to generate the activity feed of a user.

path Parameters
username
required
string

Responses

Response samples

Get users by ID

Get up to 300 users by their IDs. Users are returned in the same order as the IDs. The method is POST to allow a longer list of IDs to be sent in the request body. Please do not try to download all the Lichess users with this endpoint, or any other endpoint. An API is not a way to fully export a website. We do not provide a full download of the Lichess users. This endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day.

Request Body schema: text/plain
required

User IDs separated by commas.

string

Responses

Request samples

Content type
text/plain
thibault,maia1,maia5

Response samples

Content type
application/json
[
  • {
    }
]

Get live streamers

Get basic info about currently streaming users. This API is very fast and cheap on lichess side. So you can call it quite often (like once every 5 seconds).

Responses

Response samples

Content type
application/json
[]

Get crosstable

Get total number of games, and current score, of any two users. If the matchup flag is provided, and the users are currently playing, also gets the current match game number and scores.

path Parameters
user1
required
string
user2
required
string
query Parameters
matchup
boolean

Whether to get the current match data, if any

Responses

Response samples

Content type
application/json
{
  • "users": {
    },
  • "nbGames": 346,
  • "matchup": {
    }
}

Autocomplete usernames

Provides autocompletion options for an incomplete username.

query Parameters
term
required
string >= 3 characters

The beginning of a username

object
boolean
Default: false
  • false returns an array of usernames
  • true returns an object with matching users
friend
boolean

Returns followed players matching term if any, else returns other players. Requires OAuth.

Responses

Response samples

Content type
application/json
{
  • "result": [
    ]
}

Add a note for a user

Add a private note available only to you about this account.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault
Request Body schema: application/x-www-form-urlencoded
required
text
required
string

The contents of the note

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get notes for a user

Get the private notes that you have added for a user.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Relations

Access relations between users.

Get users followed by the logged in user

Users are streamed as ndjson.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "georges",
  • "username": "Georges",
  • "perfs": {
    },
  • "flair": "string",
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "verified": true,
  • "playTime": {
    },
  • "title": "NM",
  • "url": "https://lichess.org/@/georges",
  • "playing": "https://lichess.org/yqfLYJ5E/black",
  • "count": {
    },
  • "streaming": false,
  • "streamer": {},
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Follow a player

Follow a player, adding them to your list of Lichess friends.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Unfollow a player

Unfollow a player, removing them from your list of Lichess friends.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Block a player

Block a player, adding them to your list of blocked Lichess users.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Unblock a player

Unblock a player, removing them from your list of blocked Lichess users.

Authorizations:
OAuth2
path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Games

Access games played on Lichess. https://lichess.org/games

Export one game

Download one game in either PGN or JSON format. Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API.

path Parameters
gameId
required
string

The game ID (8 characters).

query Parameters
moves
boolean
Default: true

Include the PGN moves.

pgnInJson
boolean
Default: false

Include the full PGN within the JSON response, in a pgn field.

tags
boolean
Default: true

Include the PGN tags.

clocks
boolean
Default: true

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

evals
boolean
Default: true

Include analysis evaluations and comments, when available. Either as PGN comments: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] } Or in an analysis JSON field, depending on the response type.

accuracy
boolean
Default: false

Include accuracy percent of each player, when available.

opening
boolean
Default: true

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

division
boolean
Default: true

Plies which mark the beginning of the middlegame and endgame. Only available in JSON

literate
boolean
Default: false

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. Example: 5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)

withBookmarked
boolean
Default: false

Add a bookmarked: true JSON field when the logged in user has bookmarked the game. The response type must be set to application/x-ndjson by the request Accept header.

players
string

URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. Example: https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt

Responses

Response samples

Content type
No sample

Export ongoing game of a user

Download the ongoing game, or the last game played, of a user. Available in either PGN or JSON format. Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API.

path Parameters
username
required
string
query Parameters
moves
boolean
Default: true

Include the PGN moves.

pgnInJson
boolean
Default: false

Include the full PGN within the JSON response, in a pgn field.

tags
boolean
Default: true

Include the PGN tags.

clocks
boolean
Default: true

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

evals
boolean
Default: true

Include analysis evaluations and comments, when available. Either as PGN comments: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] } Or in an analysis JSON field, depending on the response type.

accuracy
boolean
Default: false

Include accuracy percent of each player, when available.

opening
boolean
Default: true

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

division
boolean
Default: false

Plies which mark the beginning of the middlegame and endgame. Only available in JSON

literate
boolean
Default: false

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. Example: 5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)

players
string

URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. Example: https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt

Responses

Response samples

Content type
No sample

Export games of a user

Download all games of any user in PGN or ndjson format. Games are sorted by reverse chronological order (most recent first). We recommend streaming the response, for it can be very long. https://lichess.org/@/german11 for instance has more than 500,000 games. The game stream is throttled, depending on who is making the request:

  • Anonymous request: 20 games per second
  • OAuth2 authenticated request: 30 games per second
  • Authenticated, downloading your own games: 60 games per second
Authorizations:
OAuth2
path Parameters
username
required
string

The user name.

query Parameters
since
integer >= 1356998400070

Download games played since this timestamp. Defaults to account creation date.

until
integer >= 1356998400070

Download games played until this timestamp. Defaults to now.

max
integer >= 1

How many games to download. Leave empty to download all games.

vs
string

[Filter] Only games played against this opponent

rated
boolean

[Filter] Only rated (true) or casual (false) games

perfType
string
Default: null
Enum: "ultraBullet" "bullet" "blitz" "rapid" "classical" "correspondence" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

[Filter] Only games in these speeds or variants. Multiple perf types can be specified, separated by a comma. Example: blitz,rapid,classical

color
string
Enum: "white" "black"

[Filter] Only games played as this color.

analysed
boolean

[Filter] Only games with or without a computer analysis available

moves
boolean
Default: true

Include the PGN moves.

pgnInJson
boolean
Default: false

Include the full PGN within the JSON response, in a pgn field. The response type must be set to application/x-ndjson by the request Accept header.

tags
boolean
Default: true

Include the PGN tags.

clocks
boolean
Default: false

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

evals
boolean
Default: false

Include analysis evaluations and comments, when available. Either as PGN comments: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] } Or in an analysis JSON field, depending on the response type.

accuracy
boolean
Default: false

Include accuracy percent of each player, when available.

opening
boolean
Default: false

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

division
boolean
Default: false

Plies which mark the beginning of the middlegame and endgame. Only available in JSON

ongoing
boolean
Default: false

Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API.

finished
boolean
Default: true

Include finished games. Set to false to only get ongoing games.

literate
boolean
Default: false

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. Example: 5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)

lastFen
boolean
Default: false

Include the FEN notation of the last position of the game. The response type must be set to application/x-ndjson by the request Accept header.

withBookmarked
boolean
Default: false

Add a bookmarked: true JSON field when the logged in user has bookmarked the game. The response type must be set to application/x-ndjson by the request Accept header.

players
string

URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. Example: https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt

sort
string
Default: "dateDesc"
Enum: "dateAsc" "dateDesc"

Sort order of the games.

Responses

Response samples

Content type
No sample

Export games by IDs

Download games by IDs in PGN or ndjson format, depending on the request Accept header. Games are sorted by reverse chronological order (most recent first) The method is POST so a longer list of IDs can be sent in the request body. 300 IDs can be submitted. Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API.

query Parameters
moves
boolean
Default: true

Include the PGN moves.

pgnInJson
boolean
Default: false

Include the full PGN within the JSON response, in a pgn field.

tags
boolean
Default: true

Include the PGN tags.

clocks
boolean
Default: false

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

evals
boolean
Default: false

Include analysis evaluations and comments, when available. Either as PGN comments: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] } Or in an analysis JSON field, depending on the response type.

accuracy
boolean
Default: false

Include accuracy percent of each player, when available.

opening
boolean
Default: false

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

division
boolean
Default: false

Plies which mark the beginning of the middlegame and endgame. Only available in JSON

literate
boolean
Default: false

Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. Example: 5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)

players
string

URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. Example: https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt

Request Body schema: text/plain
required

Game IDs separated by commas. Up to 300.

string

Responses

Request samples

Content type
text/plain
TJxUmbWK,4OtIh2oh,ILwozzRZ

Response samples

Content type
No sample

Stream games of users

Stream the games played between a list of users, in real time. Only games where both players are part of the list are included. The stream emits an event each time a game is started or finished. To also get all current ongoing games at the beginning of the stream, use the withCurrentGames flag. Games are streamed as ndjson. Maximum number of users: 300. The method is POST so a longer list of IDs can be sent in the request body.

query Parameters
withCurrentGames
boolean
Default: false

Include the already started games at the beginning of the stream.

Request Body schema: text/plain
required

Up to 300 user IDs separated by commas. Example: thibault,maia1,maia5

string

Responses

Response samples

Content type
application/x-ndjson
[
  • {
    }
]

Stream games by IDs

Creates a stream of games from an arbitrary streamId, and a list of game IDs. The stream first outputs the games that already exists, then emits an event each time a game is started or finished. Games are streamed as ndjson. Maximum number of games: 500 for anonymous requests, or 1000 for OAuth2 authenticated requests. While the stream is open, it is possible to add new game IDs to watch.

path Parameters
streamId
required
string
Example: myAppName-someRandomId

Arbitrary stream ID that you can later use to add game IDs to the stream.

Request Body schema: text/plain
required

Up to 500 or 1000 game IDs separated by commas. Example: gameId01,gameId02,gameId03

string

Responses

Response samples

Content type
application/x-ndjson
[
  • {
    }
]

Add game IDs to stream

Add new game IDs for an existing stream to watch. The stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished.

path Parameters
streamId
required
string
Example: myAppName-someRandomId

The stream ID you used to create the stream.

Request Body schema: text/plain
required

Up to 500 or 1000 game IDs separated by commas. Example: gameId04,gameId05,gameId06

string

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get my ongoing games

Get the ongoing games of the current user. Real-time and correspondence games are included. The most urgent games are listed first.

Authorizations:
OAuth2
query Parameters
nb
integer [ 1 .. 50 ]
Default: 9

Max number of games to fetch

Responses

Response samples

Content type
application/json
{
  • "nowPlaying": [
    ]
}

Stream moves of a game

Stream positions and moves of any ongoing game, in ndjson. A description of the game is sent as a first message. Then a message is sent each time a move is played. Finally a description of the game is sent when it finishes, and the stream is closed. Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. No more than 8 game streams can be opened at the same time from the same IP address.

path Parameters
id
required
string
Example: LuGQwhBb

Responses

Response samples

Content type
application/x-ndjson
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Import one game

Import a game from PGN. See https://lichess.org/paste. Rate limiting: 200 games per hour for OAuth requests, 100 games per hour for anonymous requests. To broadcast ongoing games, consider pushing to a broadcast instead. To analyse a position or a line, just construct an analysis board URL: https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+

Authorizations:
OAuth2
Request Body schema: application/x-www-form-urlencoded
required

A single game to import

pgn
string

The PGN. It can contain only one game. Most standard tags are supported.

Responses

Response samples

Content type
application/json
{}

Export your imported games

Download all games imported by you. Games are exported in PGN format.

Authorizations:
OAuth2

Responses

TV

Access Lichess TV channels and games. https://lichess.org/tv & https://lichess.org/games

Get current TV games

Get basic info about the best games being played for each speed and variant, but also computer games and bot games. See lichess.org/tv.

Responses

Response samples

Content type
application/json
{
  • "bot": {
    },
  • "blitz": {
    },
  • "racingKings": {
    },
  • "ultraBullet": {
    },
  • "bullet": {
    },
  • "classical": {
    },
  • "threeCheck": {
    },
  • "antichess": {
    },
  • "computer": {
    },
  • "horde": {
    },
  • "rapid": {
    },
  • "atomic": {
    },
  • "crazyhouse": {
    },
  • "chess960": {
    },
  • "kingOfTheHill": {
    },
  • "best": {
    }
}

Stream current TV game

Stream positions and moves of the current TV game in ndjson. Try it with curl https://lichess.org/api/tv/feed.

Responses

Response samples

Content type
application/x-ndjson
Example
{
  • "t": "featured",
  • "d": {
    }
}

Stream current TV game of a TV channel

Stream positions and moves of a current TV channel's game in ndjson. Try it with curl https://lichess.org/api/tv/rapid/feed.

path Parameters
channel
required
string

The name of the channel in camel case.

Responses

Response samples

Content type
application/x-ndjson
Example
{
  • "t": "featured",
  • "d": {
    }
}

Get best ongoing games of a TV channel

Get a list of ongoing games for a given TV channel. Similar to lichess.org/games. Available in PGN or ndjson format, depending on the request Accept header.

path Parameters
channel
required
string

The name of the channel in camel case.

query Parameters
nb
number [ 1 .. 30 ]
Default: 10

Number of games to fetch.

moves
boolean
Default: true

Include the PGN moves.

pgnInJson
boolean
Default: false

Include the full PGN within the JSON response, in a pgn field.

tags
boolean
Default: true

Include the PGN tags.

clocks
boolean
Default: false

Include clock status when available. Either as PGN comments: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] } Or in a clocks JSON field, as centisecond integers, depending on the response type.

opening
boolean
Default: false

Include the opening name. Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

Responses

Response samples

Content type
No sample

Puzzles

Access Lichess puzzle history and dashboard.

Our collection of puzzles is in the public domain, you can download it here. For a list of our puzzle themes with their description, check out the theme translation file. The daily puzzle can be posted in your slack workspace.

Get the daily puzzle

Get the daily Lichess puzzle in JSON format. Alternatively, you can post it in your slack workspace.

Responses

Response samples

Content type
application/json
{
  • "game": {
    },
  • "puzzle": {
    }
}

Get a puzzle by its ID

Get a single Lichess puzzle in JSON format.

path Parameters
id
required
string

The puzzle ID

Responses

Response samples

Content type
application/json
{
  • "game": {
    },
  • "puzzle": {
    }
}

Get your puzzle activity

Download your puzzle activity in ndjson format. Puzzle activity is sorted by reverse chronological order (most recent first) We recommend streaming the response, for it can be very long.

Authorizations:
OAuth2
query Parameters
max
integer >= 1

How many entries to download. Leave empty to download all activity.

before
integer >= 1356998400070

Download entries before this timestamp. Defaults to now. Use before and max for pagination.

Responses

Response samples

Content type
application/x-ndjson
{
  • "date": 1717460624888,
  • "puzzle": {
    },
  • "win": true
}

Get your puzzle dashboard

Download your puzzle dashboard as JSON. Also includes all puzzle themes played, with aggregated results. Allows re-creating the improvement/strengths interfaces.

Authorizations:
OAuth2
path Parameters
days
required
integer >= 1

How many days to look back when aggregating puzzle results. 30 is sensible.

Responses

Response samples

Content type
application/json
{
  • "days": 30,
  • "global": {
    },
  • "themes": {
    }
}

Get the storm dashboard of a player

Download the storm dashboard of any player as JSON. Contains the aggregated highscores, and the history of storm runs aggregated by days. Use ?days=0 if you only care about the highscores.

path Parameters
username
required
string

Username of the player

query Parameters
days
integer [ 0 .. 365 ]
Default: 30

How many days of history to return

Responses

Response samples

Content type
application/json
{
  • "days": [
    ],
  • "high": {
    }
}

Create and join a puzzle race

Create a new private puzzle race. The Lichess user who creates the race must join the race page, and manually start the race when enough players have joined.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{}

Teams

Access and manage Lichess teams and their members. https://lichess.org/team

Get team swiss tournaments

Get all swiss tournaments of a team. Tournaments are sorted by reverse chronological order of start date (last starting first). Tournaments are streamed as ndjson.

path Parameters
teamId
required
string
Example: coders
query Parameters
max
integer >= 1
Default: 100

How many tournaments to download.

Responses

Response samples

Content type
application/nd-json
{
  • "clock": {
    },
  • "createdBy": "lichess",
  • "id": "SuwsOIhE",
  • "name": "Rapid",
  • "nbOngoing": 0,
  • "nbPlayers": 37,
  • "nbRounds": 7,
  • "rated": true,
  • "round": 7,
  • "startsAt": "2024-06-11T02:00:00Z",
  • "stats": {
    },
  • "status": "finished",
  • "variant": "standard",
  • "verdicts": {
    }
}

Get a single team

Public info about a team. Includes the list of publicly visible leaders.

path Parameters
teamId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "lichess-swiss",
  • "name": "Lichess Swiss",
  • "description": "The official Lichess Swiss team. We organize regular swiss tournaments for all to join.",
  • "flair": "food-drink.cheese-wedge",
  • "leader": {
    },
  • "leaders": [
    ],
  • "nbMembers": 487629,
  • "open": true,
  • "joined": false,
  • "requested": false
}

Get popular teams

Paginator of the most popular teams.

query Parameters
page
number
Default: 1
Example: page=1

Responses

Response samples

Content type
application/json
{
  • "currentPage": 4,
  • "maxPerPage": 15,
  • "currentPageResults": [
    ],
  • "nbResults": 205194,
  • "previousPage": 3,
  • "nextPage": 5,
  • "nbPages": 13680
}

Teams of a player

All the teams a player is a member of.

path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search teams

Paginator of team search results for a keyword.

query Parameters
text
string
Example: text=coders
page
number
Default: 1
Example: page=1

Responses

Response samples

Content type
application/json
{
  • "currentPage": 4,
  • "maxPerPage": 15,
  • "currentPageResults": [
    ],
  • "nbResults": 205194,
  • "previousPage": 3,
  • "nextPage": 5,
  • "nbPages": 13680
}

Get members of a team

Members are sorted by reverse chronological order of joining the team (most recent first). OAuth is only required if the list of members is private. Up to 5,000 users are streamed as ndjson.

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
query Parameters
full
boolean
Default: false

Full user documents with performance ratings. This limits the response to 1,000 users.

Responses

Response samples

Content type
application/x-ndjson
{
  • "joinedTeamAt": 1716930043067,
  • "id": "chess-network",
  • "name": "Chess-Network",
  • "title": "NM",
  • "patron": true
}

Get team Arena tournaments

Get all Arena tournaments relevant to a team. Tournaments are sorted by reverse chronological order of start date (last starting first). Tournaments are streamed as ndjson.

path Parameters
teamId
required
string

ID of the team

query Parameters
max
integer >= 1
Default: 100

How many tournaments to download.

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "XhfVxYPG",
  • "createdBy": "lichess",
  • "system": "arena",
  • "minutes": 27,
  • "clock": {
    },
  • "rated": true,
  • "fullName": "Hourly Bullet Arena",
  • "nbPlayers": 4,
  • "variant": {
    },
  • "startsAt": 1716930043067,
  • "finishesAt": 1716931663067,
  • "status": 10,
  • "perf": {
    },
  • "secondsToStart": 871,
  • "minRatedGames": {
    },
  • "schedule": {
    }
}

Join a team

Join a team. If the team requires a password but the password field is incorrect, then the call fails with 403 Forbidden. Similarly, if the team join policy requires a confirmation but the message parameter is not given, then the call fails with 403 Forbidden.

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
Request Body schema: application/x-www-form-urlencoded
required
message
string [ 30 .. 2000 ] characters

Required if team manually reviews admission requests.

password
string

Optional password, if the team requires one.

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Leave a team

Leave a team.

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Get join requests

Get pending join requests of your team

Authorizations:
OAuth2
path Parameters
teamId
required
string
query Parameters
declined
boolean
Default: false

Get the declined join requests

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Accept join request

Accept someone's request to join your team

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
userId
required
string
Example: neio

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Decline join request

Decline someone's request to join your team

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
userId
required
string
Example: neio

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Kick a user from your team

Kick a member out of one of your teams.

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
userId
required
string
Example: neio

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Message all members

Send a private message to all members of a team. You must be a team leader with the "Messages" permission.

Authorizations:
OAuth2
path Parameters
teamId
required
string
Example: coders
Request Body schema: application/x-www-form-urlencoded
required
message
string

The message to send to all your team members.

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Board

Play on Lichess with physical boards and third-party clients. Works with normal Lichess accounts. Engine play or assistance is forbidden.

Features

Restrictions

Stream incoming events

Stream the events reaching a lichess user in real time as ndjson.

An empty line is sent every 6 seconds for keep alive purposes.

Each non-empty line is a JSON object containing a type field. Possible values are:

  • gameStart Start of a game
  • gameFinish Completion of a game
  • challenge A player sends you a challenge or you challenge someone
  • challengeCanceled A player cancels their challenge to you
  • challengeDeclined The opponent declines your challenge

When the stream opens, all current challenges and games are sent.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/x-ndjson
Example
{
  • "type": "gameStart",
  • "game": {
    }
}

Create a seek

Create a public seek, to start a game with a random player.

Real-time seek

Specify the time and increment clock values. The response is streamed but doesn't contain any information.

Keep the connection open to keep the seek active.

If the client closes the connection, the seek is canceled. This way, if the client terminates, the user won't be paired in a game they wouldn't play. When the seek is accepted, or expires, the server closes the connection.

Make sure to also have an Event stream open, to be notified when a game starts. We recommend opening the Event stream first, then the seek stream. This way, you won't miss the game event if the seek is accepted immediately.

Correspondence seek

Specify the days per turn value. The response is not streamed, it immediately completes with the seek ID. The seek remains active on the server until it is joined by someone.

Authorizations:
OAuth2
Request Body schema: application/x-www-form-urlencoded
required

Parameters of the seek

rated
boolean
Default: false

Whether the game is rated and impacts players ratings.

time
number [ 0 .. 180 ]

Clock initial time in minutes. Required for real-time seeks.

increment
integer [ 0 .. 180 ]

Clock increment in seconds. Required for real-time seeks.

days
integer
Enum: 1 2 3 5 7 10 14

Days per turn. Required for correspondence seeks.

variant
string (VariantKey)
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck" "fromPosition"
color
string
Default: "random"
Enum: "random" "white" "black"

The color to play. Better left empty to automatically get 50% white.

ratingRange
string

The rating range of potential opponents. Better left empty. Example: 1500-1800

Responses

Response samples

Content type
text/plain
Stream Board game state 
 Stream the state of a game being played with the Board API, as ndjson.


Use this endpoint to get updates about the game in real-time, with a single request.


Each line is a JSON object containing a type field. Possible values are:


    

  • gameFull Full game data. All values are immutable, except for the state field.
    

    • 

  • gameState Current state of the game. Immutable values not included. Sent when a move is played, a draw is offered, or when the game ends.
    

    • 

  • chatLine Chat message sent by a user in the room "player" or "spectator".
    

    • 

  • opponentGone Whether the opponent has left the game, and how long before you can claim a win or draw.
    

    • 



The first line is always of type gameFull.


The server closes the stream when the game ends, or if the game has already ended.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/x-ndjson
Example
{
  • "id": "QdzzBlzY",
  • "variant": {
    },
  • "speed": "blitz",
  • "perf": {
    },
  • "rated": true,
  • "createdAt": 1714920830966,
  • "white": {
    },
  • "black": {
    },
  • "initialFen": "startpos",
  • "clock": {
    },
  • "type": "gameFull",
  • "state": {
    }
}
Make a Board move 
Make a move in a game being played with the Board API.
The move can also contain a draw offer/agreement.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
move
required
string
 
 Example:  e2e4
The move to play, in UCI format


query Parameters
offeringDraw
boolean
 
Whether to offer (or agree to) a draw


Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Write in the chat 
Post a message to the player or spectator chat, in a game being played with the Board API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Request Body schema: application/x-www-form-urlencoded
required
room
required
string
 Enum: "player" "spectator" 
 
text
required
string
 
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Fetch the game chat 
Get the messages posted in the game chat


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/x-ndjson
[
  • {
    },
  • {
    },
  • {
    }
]
Abort a game 
Abort a game being played with the Board API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Resign a game 
Resign a game being played with the Board API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Handle draw offers 
Create/accept/decline draw offers.


    

  • yes: Offer a draw, or accept the opponent's draw offer.
    • 

  • no: Decline a draw offer from the opponent.
    • 



Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
required
boolean or "yes" (string)
 
 Example:  yes
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Handle takeback offers 
Create/accept/decline takebacks.


    

  • yes: Propose a takeback, or accept the opponent's takeback offer.
    • 

  • no: Decline a takeback offer from the opponent.
    • 



Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
required
boolean or "yes" (string)
 
 Example:  yes
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Claim victory of a game 
Claim victory when the opponent has left the game for a while.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Berserk a tournament game 
Go berserk on an arena tournament game. Halves the clock time, grants an extra point upon winning.
Only available in arena tournaments that allow berserk, and before each player has made a move.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Bot
Play on Lichess as a bot. Allows engine play.
  Read the blog post announcement of lichess bots.


  Only works with Bot accounts.


Features



Restrictions


    

  • Bots can only play challenge games:  pools and tournaments are off-limits
    • 

  • Bots cannot play UltraBullet (¼+0) because it requires making too many requests. But 0+1 and ½+0 are allowed.
    • 

  • Bots must follow Lichess TOS specifically Sandbagging, Constant Aborting, Boosting, etc
    • 

  • Bot devs are advised to make their Bots play casual only when testing their Bots logic and to avoid breaking Lichess TOS.
    • 



Integrations





Stream incoming events 
  Stream the events reaching a lichess user in real time as ndjson.


  An empty line is sent every 6 seconds for keep alive purposes.


  Each non-empty line is a JSON object containing a type field. Possible values are:


    

  • gameStart Start of a game
    • 

  • gameFinish Completion of a game
    • 

  • challenge A player sends you a challenge or you challenge someone
    • 

  • challengeCanceled A player cancels their challenge to you
    • 

  • challengeDeclined The opponent declines your challenge
    • 



  When the stream opens, all current challenges and games are sent.


Authorizations:
OAuth2
Responses
 Response samples 
Content type
application/x-ndjson
Example
{
  • "type": "gameStart",
  • "game": {
    }
}
Get online bots 
Stream the online bot users, as ndjson. Throttled to 50 bot users per second.


query Parameters
nb
integer  >= 1 
 
 Example:  nb=20
How many bot users to fetch


Responses
 Response samples 
Content type
application/x-ndjson
{
  • "id": "georges-bot",
  • "username": "Georges-bot",
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "verified": true,
  • "playTime": {
    },
  • "title": "BOT"
}
Upgrade to Bot account 
Upgrade a lichess player account into a Bot account. Only Bot accounts can use the Bot API.
The account cannot have played any game before becoming a Bot account. The upgrade is irreversible. The account will only be able to play as a Bot.
To upgrade an account to Bot, use the official lichess-bot client, or follow these steps:


    

  • Create an API access token with "Play bot moves" permission.
    • 

  • curl -d '' https://lichess.org/api/bot/account/upgrade -H "Authorization: Bearer <yourTokenHere>"
To know if an account has already been upgraded, use the Get my profile API:
the title field should be set to BOT.
    • 



Authorizations:
OAuth2
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Stream Bot game state 
 Stream the state of a game being played with the Bot API, as ndjson.


Use this endpoint to get updates about the game in real-time, with a single request.


Each line is a JSON object containing a type field. Possible values are:


    

  • gameFull Full game data. All values are immutable, except for the state field.
    

    • 

  • gameState Current state of the game. Immutable values not included.
    

    • 

  • chatLine Chat message sent by a user (or the bot itself) in the room "player" or "spectator".
    

    • 

  • opponentGone Whether the opponent has left the game, and how long before you can claim a win or draw.
    

    • 



The first line is always of type gameFull.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/x-ndjson
Example
{
  • "id": "QdzzBlzY",
  • "variant": {
    },
  • "speed": "blitz",
  • "perf": {
    },
  • "rated": true,
  • "createdAt": 1714920830966,
  • "white": {
    },
  • "black": {
    },
  • "initialFen": "startpos",
  • "clock": {
    },
  • "type": "gameFull",
  • "state": {
    }
}
Make a Bot move 
Make a move in a game being played with the Bot API.
The move can also contain a draw offer/agreement.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
move
required
string
 
 Example:  e2e4
The move to play, in UCI format


query Parameters
offeringDraw
boolean
 
Whether to offer (or agree to) a draw


Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Write in the chat 
Post a message to the player or spectator chat, in a game being played with the Bot API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Request Body schema: application/x-www-form-urlencoded
required
room
required
string
 Enum: "player" "spectator" 
 
text
required
string
 
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Fetch the game chat 
Get the messages posted in the game chat


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/x-ndjson
[
  • {
    },
  • {
    },
  • {
    }
]
Abort a game 
Abort a game being played with the Bot API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Resign a game 
Resign a game being played with the Bot API.


Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Handle draw offers 
Create/accept/decline draw offers with the Bot API.


    

  • yes: Offer a draw, or accept the opponent's draw offer.
    • 

  • no: Decline a draw offer from the opponent.
    • 



Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
required
boolean or "yes" (string)
 
 Example:  yes
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Handle takeback offers 
Create/accept/decline takebacks with the Bot API.


    

  • yes: Propose a takeback, or accept the opponent's takeback offer.
    • 

  • no: Decline a takeback offer from the opponent.
    • 



Authorizations:
OAuth2
path Parameters
gameId
required
string
 
 Example:  5IrD6Gzz
required
boolean or "yes" (string)
 
 Example:  yes
Responses
 Response samples 
Content type
application/json
{
  • "ok": true
}
Challenges
Send and receive challenges to play.


To create a lot of challenges, consider bulk pairing instead.


List your challenges 
Get a list of challenges created by or targeted at you.


Authorizations:
OAuth2
Responses
 Response samples 
Content type
application/json
{
  • "in": [
    ],
  • "out": [
    ]
}
Create a challenge 
Challenge someone to play. The targeted player can choose to accept or decline.
If the challenge is accepted, you will be notified on the event stream
that a new game has started. The game ID will be the same as the challenge ID.
Challenges for realtime games (not correspondence) expire after 20s if not accepted.
To prevent that, use the keepAliveStream flag described below.


Authorizations:
OAuth2
path Parameters
username
required
string
 
 Example:  LeelaChess
Request Body schema: application/x-www-form-urlencoded
required
Parameters of the challenge


rated
boolean
 Default:  false
 
Game is rated and impacts players ratings


clock.limit
number  [ 0 .. 10800 ] 
 
Clock initial time in seconds. If empty, a correspondence game is created. Valid values are 0, 15, 30, 45, 60, 90, and any multiple of 60 up to 10800 (3 hours).


clock.increment
integer  [ 0 .. 60 ] 
 
Clock increment in seconds. If empty, a correspondence game is created.


days
integer
 Enum: 1 2 3 5 7 10 14 
 
Days per move, for correspondence games. Clock settings must be omitted.


color
string
 Default:  "random"
 Enum: "random" "white" "black" 
 
Which color you get to play


variant
string (VariantKey) 
 Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck" "fromPosition" 
 
fen
string (FromPositionFEN) 
 
Custom initial position (in FEN). Variant must be standard, fromPosition, or chess960 (if a valid 960 starting position), and the game cannot be rated.


keepAliveStream
boolean
 
If set, the response is streamed as ndjson.
The challenge is kept alive until the connection is closed by the client.
When the challenge is accepted, declined or canceled, a message of the form {"done":"accepted"} is sent,
then the connection is closed by the server.
If not set, the response is not streamed, and the challenge expires after 20s if not accepted.


rules
string
 Enum: "noAbort" "noRematch" "noGiveTime" "noClaimWin" "noEarlyDraw" 
 
Extra game rules separated by commas.
Example: noAbort,noRematch


Responses
 Response samples 
Content type
application/json
{
  • "id": "H9fIRZUk",
  • "url": "https://lichess.org/H9fIRZUk",
  • "status": "created",
  • "challenger": {
    },
  • "destUser": {
    },
  • "variant": {
    },
  • "rated": true,
  • "speed": "rapid",
  • "timeControl": {
    },
  • "color": "random",
  • "finalColor": "black",
  • "perf": {
    },
  • "direction": "out"
}
Show one challenge 
Get details about a challenge, even if it has been recently accepted, canceled or declined.


Authorizations:
OAuth2
path Parameters
challengeId
required
string
 
The challenge ID


Responses
 Response samples 
Content type
application/json
{
  • "id": "H9fIRZUk",
  • "url": "https://lichess.org/H9fIRZUk",
  • "status": "created",
  • "challenger": {
    },
  • "destUser": {
    },
  • "variant": {