openapi: 3.1.0
info:
version: 2.0.144
title: Lichess.org API reference Account Games API
contact:
name: Lichess.org API
url: https://lichess.org/api
email: contact@lichess.org
x-logo:
url: https://lichess1.org/assets/logo/lichess-pad12.svg
license:
name: AGPL-3.0-or-later
url: https://www.gnu.org/licenses/agpl-3.0.txt
description: '# Introduction
Welcome to the reference for the Lichess API! Lichess is free/libre,
open-source chess server powered by volunteers and donations.
- Get help in the [Lichess Discord channel](https://discord.gg/lichess)
- API demo app with OAuth2 login and gameplay: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)
- API UI app with OAuth2 login and endpoint forms: [source](https://github.com/lichess-org/api-ui) / [website](https://lichess.org/api/ui)
- [Contribute to this documentation on Github](https://github.com/lichess-org/api)
- Check out [Lichess widgets to embed in your website](https://lichess.org/developers)
- [Download all Lichess rated games](https://database.lichess.org/)
- [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)
- [Download all evaluated positions](https://database.lichess.org/#evals)
## Endpoint
All requests go to `https://lichess.org` (unless otherwise specified).
## Clients
- [Python general API](https://github.com/lichess-org/berserk)
- [MicroPython general API](https://github.com/mkomon/uberserk)
- [Python general API - async](https://pypi.org/project/async-lichess-sdk)
- [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)
- [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)
- [Java general API](https://github.com/tors42/chariot)
- [JavaScript & TypeScript general API](https://github.com/devjiwonchoi/equine)
- [LichessNET - C# API Wrapper](https://github.com/Rabergsel/LichessNET)
- [.NET general API](https://github.com/Dblike/LichessSharp)
## 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](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),
you have exceded one of the rate limits.
In most cases, waiting one minute before retrying will be sufficient, but some limits may require longer.
Reduce your request frequency before retrying.
## Streaming with ND-JSON
Some API endpoints stream their responses as [Newline Delimited JSON a.k.a. **nd-json**](https://github.com/ndjson/ndjson-spec), with one JSON object per line.
Here''s a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.
## Authentication
### Which authentication method is right for me?
[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)
### Personal Access Token
Personal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.
- [Generate a personal access token](https://lichess.org/account/oauth/token)
- `curl https://lichess.org/api/account -H "Authorization: Bearer {token}"`
- [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)
### 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](https://lichess.org/account/oauth/token).
### 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](#tag/OAuth) or
the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.
- [Demo app](https://lichess-org.github.io/api-demo/)
- [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)
- [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)
- [Java example](https://github.com/tors42/lichess-oauth-pkce-app)
- [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)
#### Real life examples
- [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))
- [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))
- [English Chess Federation](https://ecf.octoknight.com/)
- [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)
### 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.
'
servers:
- url: https://lichess.org
- url: https://lichess.dev
- url: http://localhost:{port}
variables:
port:
default: '8080'
- url: http://l.org
tags:
- name: Games
description: 'Access games played on Lichess.
<https://lichess.org/games>
'
paths:
/game/export/{gameId}:
get:
operationId: gamePgn
summary: Export one game
description: 'Download one game in either PGN or JSON format.
Ongoing games are delayed by 3 moves, as to prevent cheat bots from using this API.
'
tags:
- Games
security: []
parameters:
- $ref: '#/components/parameters/AcceptPgnOrJson'
- in: path
name: gameId
description: The game ID
required: true
schema:
type: string
minLength: 8
maxLength: 8
- in: query
name: moves
description: Include the PGN moves.
schema:
type: boolean
default: true
- in: query
name: pgnInJson
description: Include the full PGN within the JSON response, in a `pgn` field.
schema:
type: boolean
default: false
- in: query
name: tags
description: Include the PGN tags.
schema:
type: boolean
default: true
- in: query
name: clocks
description: '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.
'
schema:
type: boolean
default: true
- in: query
name: evals
description: '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.
'
schema:
type: boolean
default: true
- in: query
name: accuracy
description: 'Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. Only available in JSON.
'
schema:
type: boolean
default: false
- in: query
name: opening
description: 'Include the opening name.
Example: `[Opening "King''s Gambit Accepted, King''s Knight Gambit"]`
'
schema:
type: boolean
default: true
- in: query
name: division
description: 'Plies which mark the beginning of the middlegame and endgame.
Only available in JSON
'
schema:
type: boolean
default: true
- in: query
name: literate
description: '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)`
'
schema:
type: boolean
default: false
- in: query
name: withBookmarked
description: '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.
'
schema:
type: boolean
default: false
responses:
'200':
description: The game representation.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GamePgn'
- $ref: '#/components/schemas/GameJson'
examples:
application/x-chess-pgn:
$ref: '#/components/examples/games-exportOneGame.pgn'
application/json:
$ref: '#/components/examples/games-exportOneGame.json'
/game/{gameId}/chat:
parameters:
- in: path
name: gameId
schema:
type: string
example: 5IrD6Gzz
required: true
get:
operationId: gameChatGet
summary: Fetch the spectator game chat
description: 'Get the messages posted in the public spectator chat of a game.
Games also have a private players chat, which only the 2 players can see.
'
tags:
- Games
security: []
responses:
'200':
description: The messages posted in the chat.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/SpectatorGameChat'
/api/user/{username}/current-game:
get:
operationId: apiUserCurrentGame
summary: Export ongoing game of a user
description: 'Download the ongoing game, or the last game played, of a user.
Available in either PGN or JSON format.
Ongoing games are delayed by 3 moves, as to prevent cheat bots from using this API.
'
tags:
- Games
security: []
parameters:
- $ref: '#/components/parameters/AcceptPgnOrJson'
- in: path
name: username
required: true
schema:
type: string
- in: query
name: moves
description: Include the PGN moves.
schema:
type: boolean
default: true
- in: query
name: pgnInJson
description: Include the full PGN within the JSON response, in a `pgn` field.
schema:
type: boolean
default: false
- in: query
name: tags
description: Include the PGN tags.
schema:
type: boolean
default: true
- in: query
name: clocks
description: '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.
'
schema:
type: boolean
default: true
- in: query
name: evals
description: '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.
'
schema:
type: boolean
default: true
- in: query
name: accuracy
description: 'Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. Only available in JSON.
'
schema:
type: boolean
default: false
- in: query
name: opening
description: 'Include the opening name.
Example: `[Opening "King''s Gambit Accepted, King''s Knight Gambit"]`
'
schema:
type: boolean
default: true
- in: query
name: division
description: 'Plies which mark the beginning of the middlegame and endgame.
Only available in JSON
'
schema:
type: boolean
default: false
- in: query
name: literate
description: '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)`
'
schema:
type: boolean
default: false
responses:
'200':
description: 'The ongoing (or last) game of a user.
This may be in either PGN or JSON format, depending on the `Accept` header of your request.
'
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GamePgn'
- $ref: '#/components/schemas/GameJson'
examples:
application/x-chess-pgn:
$ref: '#/components/examples/games-apiUserCurrentGamePgn.pgn'
application/json:
$ref: '#/components/examples/games-apiUserCurrentGameJson.json'
/api/games/user/{username}:
get:
operationId: apiGamesUser
summary: Export games of a user
description: "Download all games of any user in PGN or [ndjson](#description/streaming-with-nd-json) format.\nGames are sorted by reverse chronological order (most recent first).\nWe recommend streaming the response, for it can be very long.\n<https://lichess.org/@/german11> for instance has more than 500,000 games.\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#description/authentication) request: 30 games per second\n - Authenticated, downloading your own games: 60 games per second\n"
tags:
- Games
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/AcceptPgnOrNdjson'
- in: path
name: username
description: The user name.
schema:
type: string
required: true
- in: query
name: since
description: Download games played since this timestamp. Defaults to account creation date.
schema:
type: integer
minimum: 1356998400070
- in: query
name: until
description: Download games played until this timestamp. Defaults to now.
schema:
type: integer
minimum: 1356998400070
- in: query
name: max
description: How many games to download. Leave empty to download all games.
schema:
type: integer
minimum: 1
- in: query
name: vs
description: '[Filter] Only games played against this opponent'
schema:
type: string
- in: query
name: rated
description: '[Filter] Only rated (`true`) or casual (`false`) games'
schema:
type: boolean
- in: query
name: perfType
description: '[Filter] Only games in these speeds or variants.
Multiple perf types can be specified, separated by a comma.
Example: blitz,rapid,classical
'
schema:
$ref: '#/components/schemas/PerfType'
- in: query
name: color
description: '[Filter] Only games played as this color.'
schema:
type: string
enum:
- white
- black
- in: query
name: analysed
description: '[Filter] Only games with or without a computer analysis available'
schema:
type: boolean
- in: query
name: moves
description: Include the PGN moves.
schema:
type: boolean
default: true
- in: query
name: pgnInJson
description: 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.
schema:
type: boolean
default: false
- in: query
name: tags
description: Include the PGN tags.
schema:
type: boolean
default: true
- in: query
name: clocks
description: '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.
'
schema:
type: boolean
default: false
- in: query
name: evals
description: '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.
'
schema:
type: boolean
default: false
- in: query
name: accuracy
description: 'Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. Only available in JSON.
'
schema:
type: boolean
default: false
- in: query
name: opening
description: 'Include the opening name.
Example: `[Opening "King''s Gambit Accepted, King''s Knight Gambit"]`
'
schema:
type: boolean
default: false
- in: query
name: division
description: 'Plies which mark the beginning of the middlegame and endgame.
Only available in JSON
'
schema:
type: boolean
default: false
- in: query
name: ongoing
description: 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.
schema:
type: boolean
default: false
- in: query
name: finished
description: Include finished games. Set to `false` to only get ongoing games.
schema:
type: boolean
default: true
- in: query
name: literate
description: '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)`
'
schema:
type: boolean
default: false
- in: query
name: lastFen
description: 'Include the X-FEN notation of the last position of the game.
The response type must be set to `application/x-ndjson` by the request `Accept` header.
'
schema:
type: boolean
default: false
- in: query
name: withBookmarked
description: '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.
'
schema:
type: boolean
default: false
- in: query
name: sort
description: Sort order of the games.
schema:
type: string
default: dateDesc
enum:
- dateAsc
- dateDesc
responses:
'200':
description: The games of the user.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/x-ndjson:
schema:
oneOf:
- $ref: '#/components/schemas/GamePgn'
- $ref: '#/components/schemas/GameJson'
examples:
application/x-chess-pgn:
$ref: '#/components/examples/games-apiGamesUserPgn.pgn'
application/x-ndjson:
$ref: '#/components/examples/games-apiGamesUserJson.json'
/api/games/export/_ids:
post:
operationId: gamesExportIds
summary: Export games by IDs
description: 'Download games by IDs in PGN or [ndjson](#description/streaming-with-nd-json) 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 3 moves, as to prevent cheat bots from using this API.
'
tags:
- Games
security: []
requestBody:
description: Game IDs separated by commas. Up to 300.
required: true
content:
text/plain:
schema:
type: string
example: TJxUmbWK,4OtIh2oh,ILwozzRZ
parameters:
- $ref: '#/components/parameters/AcceptPgnOrNdjson'
- in: query
name: moves
description: Include the PGN moves.
schema:
type: boolean
default: true
- in: query
name: pgnInJson
description: Include the full PGN within the JSON response, in a `pgn` field.
schema:
type: boolean
default: false
- in: query
name: tags
description: Include the PGN tags.
schema:
type: boolean
default: true
- in: query
name: clocks
description: '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.
'
schema:
type: boolean
default: false
- in: query
name: evals
description: '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.
'
schema:
type: boolean
default: false
- in: query
name: accuracy
description: 'Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. Only available in JSON.
'
schema:
type: boolean
default: false
- in: query
name: opening
description: 'Include the opening name.
Example: `[Opening "King''s Gambit Accepted, King''s Knight Gambit"]`
'
schema:
type: boolean
default: false
- in: query
name: division
description: 'Plies which mark the beginning of the middlegame and endgame.
Only available in JSON
'
schema:
type: boolean
default: false
- in: query
name: literate
description: '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)`
'
schema:
type: boolean
default: false
responses:
'200':
description: The representation of the games.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/GamePgn'
- $ref: '#/components/schemas/GameJson'
examples:
application/x-chess-pgn:
$ref: '#/components/examples/games-gamesExportIds.pgn'
application/json:
$ref: '#/components/examples/games-gamesExportIds.json'
/api/stream/games-by-users:
post:
operationId: gamesByUsers
summary: Stream games of users
description: '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](#description/streaming-with-nd-json).
Maximum number of users: 300.
The method is `POST` so a longer list of IDs can be sent in the request body.
'
tags:
- Games
security: []
requestBody:
description: 'Up to 300 user IDs separated by commas.
Example: `thibault,maia1,maia5`
'
required: true
content:
text/plain:
schema:
type: string
parameters:
- in: query
name: withCurrentGames
description: Include the already started games at the beginning of the stream.
schema:
type: boolean
default: false
responses:
'200':
description: The stream of the games played between the users.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/GameStream'
/api/stream/games/{streamId}:
post:
operationId: gamesByIds
summary: Stream games by IDs
description: '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](#description/streaming-with-nd-json).
Maximum number of games: 500 for anonymous requests, or 1000 for [OAuth2 authenticated](#description/authentication) requests.
While the stream is open, it is possible to [add new game IDs to watch](#tag/games/POST/api/stream/games/{streamId}/add).
'
tags:
- Games
security: []
parameters:
- in: path
name: streamId
schema:
type: string
description: Arbitrary stream ID that you can later use to add game IDs to the stream.
example: myAppName-someRandomId
required: true
requestBody:
description: 'Up to 500 or 1000 game IDs separated by commas.
Example: `gameId01,gameId02,gameId03`
'
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: The stream of the games matching the requested IDs.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/GameStream'
/api/stream/games/{streamId}/add:
post:
operationId: gamesByIdsAdd
summary: Add game IDs to stream
description: 'Add new game IDs for [an existing stream](#tag/games/POST/api/stream/games/{streamId}) to watch.
The stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished.
'
tags:
- Games
security: []
parameters:
- in: path
name: streamId
schema:
type: string
description: The stream ID you used to [create the stream](#tag/games/POST/api/stream/games/{streamId}).
example: myAppName-someRandomId
required: true
requestBody:
description: 'Up to 500 or 1000 game IDs separated by commas.
Example: `gameId04,gameId05,gameId06`
'
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: The game IDs have been added to the stream.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/json:
schema:
$ref: '#/components/schemas/Ok'
/api/account/playing:
get:
operationId: apiAccountPlaying
summary: Get my ongoing games
description: 'Get the ongoing games of the current user.
Real-time and correspondence games are included.
The most urgent games are listed first.
'
tags:
- Games
security:
- OAuth2: []
parameters:
- in: query
name: nb
description: Max number of games to fetch
schema:
type: integer
default: 9
minimum: 1
maximum: 50
responses:
'200':
description: The ongoing games of the logged in user.
headers:
Access-Control-Allow-Origin:
schema:
type: string
default: '''*'''
content:
application/json:
schema:
type: object
required:
- nowPlaying
properties:
nowPlaying:
type: array
items:
type: object
required:
- gameId
- fullId
- color
- fen
- hasMoved
- isMyTurn
- lastMove
- opponent
- perf
- rated
- secondsLeft
- source
- speed
- variant
properties:
fullId:
type: string
gameId:
type: string
fen:
type: string
color:
$ref: '#/components/schemas/GameColor'
lastMove:
type: string
source:
$ref: '#/components/schemas/GameSource'
status:
$ref: '#/components/schemas/GameStatusName'
variant:
$ref: '#/components/schemas/Variant'
speed:
$ref: '#/components/schemas/Speed'
perf:
$ref: '#/components/schemas/PerfType'
rated:
type: boolean
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/openapi/lichess-games-api-openapi.yml