Lichess.org API reference (2.0.0)

Download OpenAPI specification:Download

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.

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.

Authentication

OAuth2

Authorization Code Flow

The authorization code flow allows your users to login with lichess.

Real life Oauth2 Authorization Code Flow examples

Personal API Token

Personal API tokens allow you to quickly interact with Lichess OAuth API.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://oauth.lichess.org/oauth/authorize
Token URL: https://oauth.lichess.org/oauth
Scopes:
  • preference:read -

    Read your preferences

  • preference:write -

    Write your preferences

  • email:read -

    Read your email address

  • challenge:read -

    Read incoming challenges

  • challenge:write -

    Create, accept, decline challenges

  • challenge:bulk -

    Create, delete, query bulk pairings

  • study:read -

    Read private studies and broadcasts

  • study:write -

    Create, update, delete studies and broadcasts

  • tournament:write -

    Create tournaments

  • puzzle:read -

    Read puzzle activity

  • team:write -

    Join, leave, and manage teams

  • msg:write -

    Send private messages to other players

  • board:play -

    Play with the Board API

  • bot:play -

    Play with the Bot API. Only for Bot accounts

Account

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

Get my profile

Public informations about the logged in user.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Get my email address

Read the email address of the logged in user.

Authorizations:
OAuth2 (email:read)

Responses

Response samples

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

Get my preferences

Authorizations:
OAuth2 (preference:read)

Responses

Response samples

Content type
application/json
{
  • "prefs": {
    }
}

Get my kid mode status

Read the kid mode status of the logged in user.

Authorizations:
OAuth2 (preference:read)

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 (preference:write)
query Parameters
v
required
boolean
Example: v=true

Kid mode status

Responses

Response samples

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

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=aliquantus,chess-network,lovlas

User IDs separated by commas. Up to 50 IDs.

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.

header Parameters
Accept
required
string
Default: application/vnd.lichess.v3+json

Responses

Response samples

Content type
application/vnd.lichess.v3+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

header Parameters
Accept
required
string
Default: application/vnd.lichess.v3+json

Responses

Response samples

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

Get user public data

Read public data of a user.

path Parameters
username
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "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 user activity

Read data to generate the activity feed of a user.

path Parameters
username
required
string

Responses

Response samples

Content type
application/json

Get users by ID

Get up to 300 users by their IDs. Users are returned in the order same order as the IDs.

The method is POST so a longer list of IDs can be sent in the request body.

Request Body schema: text/plain

User IDs separated by commas.

string

Responses

Request samples

Content type
text/plain
aliquantus,chess-network,lovlas

Response samples

Content type
application/json
[
  • {
    }
]

Get members of a team

Members are sorted by reverse chronological order of joining the team (most recent first).

Members are streamed as ndjson, i.e. one JSON object per line.

path Parameters
teamId
required
string
Example: coders

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

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": {
    }
}

Relations

Access relations between users.

Get users followed by a user

Users are streamed as ndjson, i.e. one JSON object per line.

path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Get users who follow a user

Users are streamed as ndjson, i.e. one JSON object per line.

path Parameters
username
required
string
Example: thibault

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Games

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

Export one game

Download one game in either PGN or JSON format.

Ongoing games have their last 3 moves omitted, after move 5.

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 comments in the PGN moves, when available.

Example: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }

evals
boolean
Default: true

Include analysis evaluation comments in the PGN, when available.

Example: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }

opening
boolean
Default: true

Include the opening name.

Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

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 ongoing game of a user

Download the ongoing game, or the last game played, of a user. Available in either PGN or JSON format. If the game is ongoing, the 3 last moves are omitted.

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 comments in the PGN moves, when available.

Example: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }

evals
boolean
Default: true

Include analysis evaluation comments in the PGN, when available.

Example: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }

opening
boolean
Default: true

Include the opening name.

Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

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 320,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:
path Parameters
username
required
string

The user name.

query Parameters
since
integer >= 1356998400070
Default: "Account creation date"

Download games played since this timestamp.

until
integer >= 1356998400070
Default: "Now"

Download games played until this timestamp.

max
integer >= 1
Default: null

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

vs
string

[Filter] Only games played against this opponent

rated
boolean
Default: null

[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
Default: null
Enum: "white" "black"

[Filter] Only games played as this color.

analysed
boolean
Default: null

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

ongoing
boolean
Default: false

[Filter] Also include ongoing games

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 comments in the PGN moves, when available.

Example: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }

evals
boolean
Default: false

Include analysis evaluation comments in the PGN, when available.

Example: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }

opening
boolean
Default: false

Include the opening name.

Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

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 by IDs

Download games by IDs in PGN or ndjson format.

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 have their last 3 moves omitted, after move 5.

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 comments in the PGN moves, when available.

Example: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }

evals
boolean
Default: false

Include analysis evaluation comments in the PGN, when available.

Example: 12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }

opening
boolean
Default: false

Include the opening name.

Example: [Opening "King's Gambit Accepted, King's Knight Gambit"]

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

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 current games

Stream the games played between a list of users, in real time. Only games where both players are part of the list are included.

Maximum number of users: 300.

Games are streamed as ndjson, i.e. one JSON object per line.

The method is POST so a longer list of IDs can be sent in the request body.

Request Body schema: text/plain

Up to 300 user IDs separated by commas.

string

Responses

Request samples

Content type
text/plain
aliquantus,chess-network,lovlas

Response samples

Content type
application/x-ndjson
{
  • "id": "A5fcMO3k",
  • "rated": true,
  • "variant": "standard",
  • "speed": "bullet",
  • "perf": "bullet",
  • "createdAt": 1525789431889,
  • "status": 20,
  • "clock": {
    },
  • "players": {
    }
}

Get 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:
query Parameters
nb
integer [ 1 .. 50 ]
Default: 9

Max number of games to fetch

Responses

Response samples

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

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": {
    },
  • "Racing Kings": {
    },
  • "UltraBullet": {
    },
  • "Bullet": {
    },
  • "Classical": {
    },
  • "Three-check": {
    },
  • "Antichess": {
    },
  • "Computer": {
    },
  • "Horde": {
    },
  • "Rapid": {
    },
  • "Atomic": {
    },
  • "Crazyhouse": {
    },
  • "Chess960": {
    },
  • "King of the Hill": {
    },
  • "Top Rated": {
    }
}

Stream current TV game

Stream positions and moves of the current TV game in ndjson. A summary of the game is sent as a first message, and when the featured game changes.

Try it with curl https://lichess.org/api/tv/feed.

Responses

Response samples

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

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.

After move 5, the stream intentionally remains 3 moves behind the game status, 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.

Responses

Response samples

Content type
application/x-ndjson
"{\"id\":\"LuGQwhBb\",\"variant\":{\"key\":\"standard\",\"name\":\"Standard\",\"short\":\"Std\"},\"speed\":\"blitz\",\"perf\":\"blitz\",\"rated\":true,\"initialFen\":\"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1\",\"fen\":\"rnbqkb1r/1p1ppppp/p6n/2p4Q/8/1P2P3/P1PP1PPP/RNB1KBNR w KQkq - 0 4\",\"player\":\"white\",\"turns\":6,\"startedAtTurn\":0,\"source\":\"pool\",\"status\":{\"id\":20,\"name\":\"started\"},\"createdAt\":1620029815106,\"lastMove\":\"c7c5\"}\n{\"fen\":\"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w\",\"wc\":180,\"bc\":180}\n{\"fen\":\"rnbqkbnr/pppppppp/8/8/8/4P3/PPPP1PPP/RNBQKBNR b\",\"lm\":\"e2e3\",\"wc\":180,\"bc\":180}\n{\"fen\":\"rnbqkb1r/pppppppp/7n/8/8/4P3/PPPP1PPP/RNBQKBNR w\",\"lm\":\"g8h6\",\"wc\":180,\"bc\":180}\n{\"fen\":\"rnbqkb1r/pppppppp/7n/8/8/1P2P3/P1PP1PPP/RNBQKBNR b\",\"lm\":\"b2b3\",\"wc\":177,\"bc\":180}\n{\"fen\":\"rnbqkb1r/1ppppppp/p6n/8/8/1P2P3/P1PP1PPP/RNBQKBNR w\",\"lm\":\"a7a6\",\"wc\":177,\"bc\":177}\n"

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.

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

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
{}

Puzzles

Access Lichess puzzle history and dashboard. https://lichess.org/training

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/x-ndjson
{
  • "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 (puzzle:read)
query Parameters
max
integer >= 1
Default: null

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

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": 70232,
  • "date": 1514505150384,
  • "rating": 1982,
  • "ratingDiff": 5,
  • "puzzleRating": 1877
}

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 (puzzle:read)
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
{
  • "high": {
    },
  • "days": [
    ]
}

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, i.e. one JSON object per line.

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/json
[
  • {
    }
]

Get a single team

Infos about a team

path Parameters
teamId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "coders",
  • "name": "Coders",
  • "description": "There are 10 kinds of people in the world: those who understand binary, and the others.\r\n\r\nIf you want to join the team, prove (briefly) that you can code in the request message!",
  • "open": false,
  • "leader": {
    },
  • "leaders": [
    ],
  • "nbMembers": 3129
}

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
[
  • {
    }
]

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
[
  • {
    }
]

Get members of a team

Members are sorted by reverse chronological order of joining the team (most recent first).

Members are streamed as ndjson, i.e. one JSON object per line.

path Parameters
teamId
required
string
Example: coders

Responses

Response samples

Content type
application/x-ndjson
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "playTime": {
    },
  • "language": "en-GB",
  • "title": "NM",
  • "nbFollowing": 299,
  • "nbFollowers": 2735,
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

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, i.e. one JSON object per line.

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/json
[
  • {
    }
]

Join a team

Join a team. If the team join policy requires a confirmation, and the team owner is not the oAuth app owner, and the message field is not set, then the call fails with 403 Forbidden.

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

Optional request message, if the team requires one.

password
string

Optional password, if the team requires one.

Responses

Response samples

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

Leave a team

Authorizations:
OAuth2 (team:write)
path Parameters
teamId
required
string
Example: coders

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 (team:write)
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 own the team.

Authorizations:
OAuth2 (team:write)
path Parameters
teamId
required
string
Example: coders
Request Body schema: application/x-www-form-urlencoded
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.

Each 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

  • 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 (challenge:readbot:playboard:play)

Responses

Response samples

Content type
text/plain
{"type":"challenge","challenge":{"id":"7pGLxJ4F","status":"created","challenger":{"id":"lovlas","name":"Lovlas","title":"IM","rating":2506,"patron":true,"online":true,"lag":24},"destUser":{"id":"thibot","name":"thibot","title":null,"rating":1500,"provisional":true,"online":true,"lag":45},"variant":{"key":"standard","name":"Standard","short":"Std"},"rated":true,"timeControl":{"type":"clock","limit":300,"increment":25,"show":"5+25"},"color":"random","perf":{"icon":"#","name":"Rapid"}}}
{"type":"gameStart","game":{"id":"1lsvP62l"}}

Create a seek

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

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.

If 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.

Authorizations:
OAuth2 (board:play)
Request Body schema: application/x-www-form-urlencoded

Parameters of the seek

rated
boolean
Default: false

Whether the game is rated and impacts players ratings.

time
required
number [ 0 .. 180 ]

Clock initial time in minutes.

increment
required
integer [ 0 .. 180 ]

Clock increment in seconds.

variant
string
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game.

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".

The first line is always of type gameFull.

Authorizations:
OAuth2 (board:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz

Responses

Response samples

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

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 (board:play)
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 (board:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz
Request Body schema: application/x-www-form-urlencoded
room
required
string
Enum: "player" "spectator"
text
required
string

Responses

Response samples

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

Abort a game

Abort a game being played with the Board API.

Authorizations:
OAuth2 (board:play)
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 (board:play)
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 (board:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz
accept
required
boolean
Example: yes

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.

Integrations

Stream incoming events

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

Each 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

  • 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 (challenge:readbot:playboard:play)

Responses

Response samples

Content type
text/plain
{"type":"challenge","challenge":{"id":"7pGLxJ4F","status":"created","challenger":{"id":"lovlas","name":"Lovlas","title":"IM","rating":2506,"patron":true,"online":true,"lag":24},"destUser":{"id":"thibot","name":"thibot","title":null,"rating":1500,"provisional":true,"online":true,"lag":45},"variant":{"key":"standard","name":"Standard","short":"Std"},"rated":true,"timeControl":{"type":"clock","limit":300,"increment":25,"show":"5+25"},"color":"random","perf":{"icon":"#","name":"Rapid"}}}
{"type":"gameStart","game":{"id":"1lsvP62l"}}

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 (bot:play)

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".

The first line is always of type gameFull.

Authorizations:
OAuth2 (bot:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz

Responses

Response samples

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

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 (bot:play)
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 (bot:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz
Request Body schema: application/x-www-form-urlencoded
room
required
string
Enum: "player" "spectator"
text
required
string

Responses

Response samples

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

Abort a game

Abort a game being played with the Bot API.

Authorizations:
OAuth2 (bot:play)
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 (bot:play)
path Parameters
gameId
required
string
Example: 5IrD6Gzz

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.

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.

If you also have an OAuth token with challenge:write scope for the receiving user, you can make them accept the challenge immediately by setting the acceptByToken field.

Authorizations:
OAuth2 (challenge:writebot:playboard:play)
path Parameters
username
required
string
Example: LeelaChess
Request Body schema: application/x-www-form-urlencoded

Parameters of the challenge

rated
boolean

Game is rated and impacts players ratings

clock.limit
number [ 0 .. 10800 ]

Clock initial time in seconds. If empty, a correspondence game is created.

clock.increment
integer [ 0 .. 60 ]

Clock increment in seconds. If empty, a correspondence game is created.

days
integer [ 1 .. 15 ]

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
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game

fen
string
Default: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

Custom initial position (in FEN). Variant must be standard, and the game cannot be rated. Castling moves will use UCI_Chess960 notation, for example e1h1 instead of e1g1.

acceptByToken
string

Immediately accept the challenge and create the game. Pass in an OAuth token (with the challenge:write scope) for the receiving user. On success, the response will contain a game field instead of a challenge field.

Alternatively, consider the bulk pairing API.

message
string
Default: "Your game with {opponent} is ready: {game}."

Only if acceptByToken is set.

Message that is sent to each player, when the game is created. It is sent from your user account.

{opponent}, {player} and {game} are placeholders that will be replaced with the opponent name, player name, and the game URLs.

You can omit this field to send the default message, but if you set your own message, it must at least contain the {game} placeholder.

Responses

Response samples

Content type
application/json
{
  • "id": "VU0nyvsW",
  • "color": "random",
  • "direction": "out",
  • "timeControl": {
    },
  • "variant": {
    },
  • "challenger": {
    },
  • "destUser": {
    },
  • "perf": {
    },
  • "rated": true,
  • "speed": "blitz",
  • "status": "created"
}

Accept a challenge

Accept an incoming challenge.

You should receive a gameStart event on the incoming events stream.

Authorizations:
OAuth2 (challenge:writebot:playboard:play)
path Parameters
challengeId
required
string
Example: 5IrD6Gzz

Responses

Response samples

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

Decline a challenge

Decline an incoming challenge.

Authorizations:
OAuth2 (challenge:writebot:playboard:play)
path Parameters
challengeId
required
string
Example: 5IrD6Gzz
Request Body schema: application/x-www-form-urlencoded

Details related to decline of challenge

reason
string
Enum: "generic" "later" "tooFast" "tooSlow" "timeControl" "rated" "casual" "standard" "variant" "noBot" "onlyBot"

Reason challenge was declined. It will be translated to the player's language. See the full list in the translation file.

Responses

Response samples

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

Cancel a challenge

Cancel a challenge you sent, or aborts the game if the challenge was accepted, but the game was not yet played. Note that the ID of a game is the same as the ID of the challenge that created it.

Authorizations:
OAuth2 (challenge:writebot:playboard:play)
path Parameters
challengeId
required
string
Example: 5IrD6Gzz

Responses

Response samples

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

Challenge the AI

Start a game with Lichess AI.

You will be notified on the event stream that a new game has started.

Authorizations:
OAuth2 (challenge:writebot:playboard:play)
Request Body schema: application/x-www-form-urlencoded

Parameters of the game

level
number [ 1 .. 8 ]

AI strength

clock.limit
number [ 0 .. 10800 ]

Clock initial time in seconds. If empty, a correspondence game is created.

clock.increment
integer [ 0 .. 60 ]

Clock increment in seconds. If empty, a correspondence game is created.

days
integer [ 1 .. 15 ]

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
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game

fen
string
Default: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

Custom initial position (in FEN). Variant must be standard, and the game cannot be rated.

Responses

Response samples

Content type
application/json
{
  • "id": "q7ZvsdUF",
  • "rated": true,
  • "variant": "standard",
  • "speed": "blitz",
  • "perf": "blitz",
  • "createdAt": 1514505150384,
  • "lastMoveAt": 1514505592843,
  • "status": "draw",
  • "players": {
    },
  • "opening": {
    },
  • "moves": "d4 d5 c4 c6 Nc3 e6 e4 Nd7 exd5 cxd5 cxd5 exd5 Nxd5 Nb6 Bb5+ Bd7 Qe2+ Ne7 Nxb6 Qxb6 Bxd7+ Kxd7 Nf3 Qa6 Ne5+ Ke8 Qf3 f6 Nd3 Qc6 Qe2 Kf7 O-O Kg8 Bd2 Re8 Rac1 Nf5 Be3 Qe6 Rfe1 g6 b3 Bd6 Qd2 Kf7 Bf4 Qd7 Bxd6 Nxd6 Nc5 Rxe1+ Rxe1 Qc6 f3 Re8 Rxe8 Nxe8 Kf2 Nc7 Qb4 b6 Qc4+ Nd5 Nd3 Qe6 Nb4 Ne7 Qxe6+ Kxe6 Ke3 Kd6 g3 h6 Kd3 h5 Nc2 Kd5 a3 Nc6 Ne3+ Kd6 h4 Nd8 g4 Ne6 Ke4 Ng7 Nc4+ Ke6 d5+ Kd7 a4 g5 gxh5 Nxh5 hxg5 fxg5 Kf5 Nf4 Ne3 Nh3 Kg4 Ng1 Nc4 Kc7 Nd2 Kd6 Kxg5 Kxd5 f4 Nh3+ Kg4 Nf2+ Kf3 Nd3 Ke3 Nc5 Kf3 Ke6 Ke3 Kf5 Kd4 Ne6+ Kc4",
  • "clock": {
    }
}

Open-ended challenge

Create a challenge that any 2 players can join.

Share the URL of the challenge. the first 2 players to click it will be paired for a game.

The response body also contains whiteUrl and blackUrl. You can control which color each player gets by giving them these URLs, instead of the main challenge URL.

Open challenges expire after 24h.

To directly pair 2 known players, use this endpoint instead, with the acceptByToken parameter.

Request Body schema: application/x-www-form-urlencoded

Parameters of the game

rated
boolean

Game is rated and impacts players ratings

clock.limit
number [ 0 .. 10800 ]

Clock initial time in seconds. If empty, a correspondence game is created.

clock.increment
integer [ 0 .. 60 ]

Clock increment in seconds. If empty, a correspondence game is created.

variant
string
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game

fen
string
Default: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

Custom initial position (in FEN). Variant must be standard, and the game cannot be rated.

name
string

Optional name for the challenge, that players will see on the challenge page.

Responses

Response samples

Content type
application/json
{
  • "id": "VU0nyvsW",
  • "color": "random",
  • "direction": "out",
  • "timeControl": {
    },
  • "variant": {
    },
  • "challenger": {
    },
  • "destUser": {
    },
  • "perf": {
    },
  • "rated": true,
  • "speed": "blitz",
  • "status": "created"
}

Start clocks of a game

Start the clocks of a game immediately, even if a player has not yet made a move.

Requires the OAuth tokens of both players with challenge:write scope.

If the clocks have already started, the call will have no effect.

Authorizations:
OAuth2 (challenge:write)
path Parameters
gameId
required
string

ID of the game

query Parameters
token1
string

OAuth token of a player

token2
string

OAuth token of the other player

Responses

Response samples

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

Add time to the opponent clock

Add seconds to the opponent's clock. Can be used to create games with time odds.

Authorizations:
OAuth2 (challenge:write)
path Parameters
gameId
required
string

ID of the game

seconds
required
string [ 1 .. 86400 ]

How many seconds to give

Responses

Response samples

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

Create an admin challenge

For administrators only. You are not allowed to use this endpoint. Use Create a challenge instead.

Create a challenge between any two players, without OAuth tokens. The challenge will be immediately accepted, and a game created.

Authorizations:
OAuth2 (challenge:write)
path Parameters
orig
required
string
Example: Lisa

One of the two players

dest
required
string
Example: Matilde

The other player

Request Body schema: application/x-www-form-urlencoded

Parameters of the challenge

rated
boolean

Game is rated and impacts players ratings

clock.limit
number [ 0 .. 10800 ]

Clock initial time in seconds. If empty, a correspondence game is created.

clock.increment
integer [ 0 .. 60 ]

Clock increment in seconds. If empty, a correspondence game is created.

days
integer [ 1 .. 15 ]

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
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game

fen
string
Default: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

Custom initial position (in FEN). Variant must be standard, and the game cannot be rated.

message
string
Default: "Your game with {opponent} is ready: {game}."

Message that is sent to each player, when the game is created. It is sent from your user account.

{opponent} and {game} are placeholders that will be replaced with the opponent and the game URLs.

You can omit this field to send the default message, but if you set your own message, it must at least contain the {game} placeholder.

Responses

Response samples

Content type
application/json
{
  • "id": "VU0nyvsW",
  • "color": "random",
  • "direction": "out",
  • "timeControl": {
    },
  • "variant": {
    },
  • "challenger": {
    },
  • "destUser": {
    },
  • "perf": {
    },
  • "rated": true,
  • "speed": "blitz",
  • "status": "created"
}

Bulk pairings

Create many games for other players.

These endpoints are intended for tournament organisers.

View upcoming bulk pairings

Get a list of upcoming bulk pairings you created.

Only bulk pairings that are scheduled in the future, or that have a clock start scheduled in the future, are listed.

Bulk pairings are deleted from the server after the pairings are done and the clocks have started.

Authorizations:
OAuth2 (challenge:bulk)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a bulk pairing

Schedule many games at once, up to 24h in advance.

OAuth tokens are required for all paired players, with the challenge:write scope.

You can schedule up to 500 games every 10 minutes. Contact us if you need higher limits.

The entire bulk is rejected if:

  • a token is missing
  • a token is present more than once
  • a token lacks the challenge:write scope
  • a player account is closed
  • a player is paired more than once
  • a bulk is already scheduled to start at the same time with the same player
  • you have 10 scheduled bulks
  • you have 1000 scheduled games

Partial bulks are never created. Either it all fails, or it all succeeds. When it fails, it does so with an error message explaining the issue. Failed bulks are not counted in the rate limiting, they are free. Fix the issues, manually or programmatically, then retry to schedule the bulk.

A successful bulk creation returns a JSON bulk document. Its ID can be used for further operations.

Authorizations:
OAuth2 (challenge:bulk)
Request Body schema: application/x-www-form-urlencoded

Parameters of the pairings

players
string

OAuth tokens of all the players to pair, with the syntax tokenOfWhitePlayerInGame1:tokenOfBlackPlayerInGame1,tokenOfWhitePlayerInGame2:tokenOfBlackPlayerInGame2,....

The 2 tokens of the players of a game are separated with :. The first token gets the white pieces. Games are separated with ,.

Up to 1000 tokens can be sent, for a max of 500 games.

Each token must be included at most once.

Example: token1:token2,token3:token4,token5:token6

clock.limit
number [ 0 .. 10800 ]

Clock initial time in seconds. Example: 600

clock.increment
integer [ 0 .. 60 ]

Clock increment in seconds. Example: 5

pairAt
integer

Date at which the games will be created. Up to 24h in the future. Omit, or set to current date and time, to start the games immediately. Example: 1612289869919

startClocksAt
integer

Date at which the clocks will be automatically started. Up to 24h in the future. Note that the clocks can start earlier than specified, if players start making moves in the game. If omitted, the clocks will not start automatically. Example: 1612289869919

rated
boolean

Game is rated and impacts players ratings

variant
string
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant of the game

message
string
Default: "Your game with {opponent} is ready: {game}."

Message that will be sent to each player, when the game is created. It is sent from your user account.

{opponent} and {game} are placeholders that will be replaced with the opponent and the game URLs.

You can omit this field to send the default message, but if you set your own message, it must at least contain the {game} placeholder.

Responses

Response samples

Content type
application/json
{
  • "id": "RVAcwgg7",
  • "games": [
    ],
  • "variant": "standard",
  • "clock": {
    },
  • "pairAt": 1612289869919,
  • "pairedAt": null,
  • "rated": false,
  • "startClocksAt": 1612200422971,
  • "scheduledAt": 1612203514628
}

Manually start clocks

Immediately start all clocks of the games of a bulk pairing.

This overrides the startClocksAt value of an existing bulk pairing.

If the games have not yet been created (bulk.pairAt is in the future), then this does nothing.

If the clocks have already started (bulk.startClocksAt is in the past), then this does nothing.

Authorizations:
OAuth2 (challenge:bulk)
path Parameters
id
required
string
Example: 5IrD6Gzz

The ID of the bulk pairing

Responses

Response samples

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

Cancel a bulk pairing

Cancel and delete a bulk pairing that is scheduled in the future.

If the games have already been created, then this does nothing.

Canceling a bulk pairing does not refund the rate limit cost of that bulk pairing.

Authorizations:
OAuth2 (challenge:bulk)
path Parameters
id
required
string
Example: 5IrD6Gzz

The ID of the bulk pairing

Responses

Response samples

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

Arena tournaments

Access Arena tournaments played on Lichess. Official Arena tournaments are maintained by Lichess, but you can create your own Arena tournaments as well.

Get current tournaments

Get recently finished, ongoing, and upcoming tournaments.

This API is used to display the Lichess tournament schedule.

Responses

Response samples

Content type
application/json
{
  • "created": [
    ],
  • "started": [
    ],
  • "finished": [
    ]
}

Create a new Arena tournament

Create a public or private Arena tournament.

This endpoint mirrors the form on https://lichess.org/tournament/new.

You can create up to 12 public tournaments per day, or 24 private tournaments.

A team battle can be created by specifying the teambBattleByTeam argument.

Authorizations:
OAuth2 (tournament:write)
Request Body schema: application/x-www-form-urlencoded

Parameters of the tournament

name
string

The tournament name. Leave empty to get a random Grandmaster name

clockTime
required
number [ 0 .. 60 ]
Enum: 0 0.25 0.5 0.75 1 1.5 2 3 4 5 6 7 10 15 20 25 30 40 50 60

Clock initial time in minutes

clockIncrement
required
integer [ 0 .. 60 ]

Clock increment in seconds

minutes
required
integer [ 0 .. 360 ]

How long the tournament lasts, in minutes

waitMinutes
integer [ 0 .. 360 ]
Default: 5

How long to wait before starting the tournament, from now, in minutes

startDate
integer

Timestamp to start the tournament at a given date and time. Overrides the waitMinutes setting

variant
string
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant to use in tournament games

rated
boolean
Default: true

Games are rated and impact players ratings

position
string

Custom initial position (in FEN) for all games of the tournament. Must be a legal chess position. Only works with standard chess, not variants (except Chess960).

berserkable
boolean
Default: true

Whether the players can use berserk

streakable
boolean
Default: true

After 2 wins, consecutive wins grant 4 points instead of 2.

hasChat
boolean
Default: true

Whether the players can discuss in a chat

description
string

Anything you want to tell players about the tournament

password
string

Make the tournament private, and restrict access with a password

teambBattleByTeam
string

Set the ID of a team you lead to create a team battle. The other teams can be added using the team battle edit endpoint.

conditions.teamMember.teamId
string

Restrict entry to members of a team.

The teamId is the last part of a team URL, e.g. https://lichess.org/team/coders has teamId = coders.

Leave empty to let everyone join the tournament.

Do not use this to create team battles, use teamBattleByTeam instead.

conditions.minRating.rating
integer

Minimum rating to join. Leave empty to let everyone join the tournament.

conditions.maxRating.rating
integer

Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.

conditions.nbRatedGame.nb
integer

Minimum number of rated games required to join.

Responses

Response samples

Content type
application/json
{
  • "id": "QITRjufu",
  • "fullName": "U1700 SuperBlitz Arena",
  • "clock": {
    },
  • "minutes": 57,
  • "createdBy": "lichess",
  • "system": "arena",
  • "secondsToStart": 0,
  • "secondsToFinish": 36000,
  • "isFinished": true,
  • "isRecentlyFinished": true,
  • "pairingsClosed": true,
  • "startsAt": "2018-04-04T01:00:00.000Z",
  • "nbPlayers": 154,
  • "perf": {
    },
  • "schedule": {
    },
  • "variant": {
    },
  • "duels": [
    ],
  • "standings": {
    },
  • "featured": {
    },
  • "podium": [
    ],
  • "stats": {
    }
}

Get info about an Arena tournament

Get detailed info about recently finished, current, or upcoming tournament's duels, player standings, and other info.

path Parameters
id
required
string

The tournament ID.

query Parameters
page
number [ 1 .. 200 ]
Default: 1
Example: page=1

Specify which page of player standings to view.

Responses

Response samples

Content type
application/json
{
  • "id": "QITRjufu",
  • "fullName": "U1700 SuperBlitz Arena",
  • "clock": {
    },
  • "minutes": 57,
  • "createdBy": "lichess",
  • "system": "arena",
  • "secondsToStart": 0,
  • "secondsToFinish": 36000,
  • "isFinished": true,
  • "isRecentlyFinished": true,
  • "pairingsClosed": true,
  • "startsAt": "2018-04-04T01:00:00.000Z",
  • "nbPlayers": 154,
  • "perf": {
    },
  • "schedule": {
    },
  • "variant": {
    },
  • "duels": [
    ],
  • "standings": {
    },
  • "featured": {
    },
  • "podium": [
    ],
  • "stats": {
    }
}

Update an Arena tournament

Update an Arena tournament.

Be mindful not to make important changes to ongoing tournaments.

Can be used to update a team battle.

Authorizations:
OAuth2 (tournament:write)
path Parameters
id
required
string

The tournament ID.

Request Body schema: application/x-www-form-urlencoded

Parameters of the tournament

name
string

The tournament name. Leave empty to get a random Grandmaster name

clockTime
required
number [ 0 .. 60 ]
Enum: 0 0.25 0.5 0.75 1 1.5 2 3 4 5 6 7 10 15 20 25 30 40 50 60

Clock initial time in minutes

clockIncrement
required
integer [ 0 .. 60 ]

Clock increment in seconds

minutes
required
integer [ 0 .. 360 ]

How long the tournament lasts, in minutes

waitMinutes
integer [ 0 .. 360 ]
Default: 5

How long to wait before starting the tournament, from now, in minutes

startDate
integer

Timestamp to start the tournament at a given date and time. Overrides the waitMinutes setting

variant
string
Default: "standard"
Enum: "standard" "chess960" "crazyhouse" "antichess" "atomic" "horde" "kingOfTheHill" "racingKings" "threeCheck"

The variant to use in tournament games

rated
boolean
Default: true

Games are rated and impact players ratings

position
string

Custom initial position (in FEN) for all games of the tournament. Must be a legal chess position. Only works with standard chess, not variants (except Chess960).

berserkable
boolean
Default: true

Whether the players can use berserk

streakable
boolean
Default: true

After 2 wins, consecutive wins grant 4 points instead of 2.

hasChat
boolean
Default: true

Whether the players can discuss in a chat

description
string

Anything you want to tell players about the tournament

password
string

Make the tournament private, and restrict access with a password

conditions.minRating.rating
integer

Minimum rating to join. Leave empty to let everyone join the tournament.

conditions.maxRating.rating
integer

Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.

conditions.nbRatedGame.nb
integer

Minimum number of rated games required to join.

Responses

Response samples

Content type
application/json
{
  • "id": "QITRjufu",
  • "fullName": "U1700 SuperBlitz Arena",
  • "clock": {
    },
  • "minutes": 57,
  • "createdBy": "lichess",
  • "system": "arena",
  • "secondsToStart": 0,
  • "secondsToFinish": 36000,
  • "isFinished": true,
  • "isRecentlyFinished": true,
  • "pairingsClosed": true,
  • "startsAt": "2018-04-04T01:00:00.000Z",
  • "nbPlayers": 154,
  • "perf": {
    },
  • "schedule": {
    },
  • "variant": {
    },
  • "duels": [
    ],
  • "standings": {
    },
  • "featured": {
    },
  • "podium": [
    ],
  • "stats": {
    }
}

Join an Arena tournament

Join an Arena tournament, possibly with a password and/or a team.

Authorizations:
OAuth2 (tournament:write)
path Parameters
id
required
string
Example: hL7vMrFQ

The tournament ID.

Request Body schema: application/x-www-form-urlencoded

You may need these depending on the tournament to join

password
string

The tournament password, if one is required

team
string

The team to join the tournament with, for team battle tournaments

Responses

Response samples

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

Terminate an Arena tournament

Terminate an Arena tournament

Authorizations:
OAuth2 (tournament:write)
path Parameters
id
required
string
Example: hL7vMrFQ

The tournament ID.

Responses

Response samples

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

Update a team battle

Set the teams and number of leaders of a team battle.

To update the other attributes of a team battle, use the tournament update endpoint.

Authorizations:
OAuth2 (tournament:write)
path Parameters
id
required
string

The tournament ID (8 characters)..

Request Body schema: application/x-www-form-urlencoded
teams
required
string

All team IDs of the team battle, separated by commas. Make sure to always send the full list. Teams that are not in the list will be removed from the team battle.

Example: coders,zhigalko_sergei-fan-club,hhSwTKZv

nbLeaders
required
integer

Number team leaders per team.

Responses

Response samples

Content type
application/json
{
  • "id": "QITRjufu",
  • "fullName": "U1700 SuperBlitz Arena",
  • "clock": {
    },
  • "minutes": 57,
  • "createdBy": "lichess",
  • "system": "arena",
  • "secondsToStart": 0,
  • "secondsToFinish": 36000,
  • "isFinished": true,
  • "isRecentlyFinished": true,
  • "pairingsClosed": true,
  • "startsAt": "2018-04-04T01:00:00.000Z",
  • "nbPlayers": 154,
  • "perf": {
    },
  • "schedule": {
    },
  • "variant": {
    },
  • "duels": [
    ],
  • "standings": {