openapi: 3.1.0 info: version: 2.0.144 title: Lichess.org API reference Account Simuls 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: Simuls description: 'Access simuls played on Lichess. ' paths: /api/simul: get: operationId: apiSimul summary: Get current simuls description: 'Get recently created, started, finished, simuls. Created and finished simul lists are not exhaustives, only those with strong enough host will be listed, the same filter is used to display simuls on https://lichess.org/simul. When [authenticated with OAuth2](#description/authentication), the pending list will be populated with your created, but unstarted simuls. ' tags: - Simuls security: [] responses: '200': description: The list of simuls. headers: Access-Control-Allow-Origin: schema: type: string default: '''*''' content: application/json: schema: type: object properties: pending: type: array items: $ref: '#/components/schemas/Simul' created: type: array items: $ref: '#/components/schemas/Simul' started: type: array items: $ref: '#/components/schemas/Simul' finished: type: array items: $ref: '#/components/schemas/Simul' examples: default: $ref: '#/components/examples/simuls-getCurrentSimuls.json' components: schemas: Flair: type: string description: See [available flair list and images](https://github.com/lichess-org/lila/tree/master/public/flair) LightUser: type: object properties: id: type: string name: type: string flair: $ref: '#/components/schemas/Flair' title: $ref: '#/components/schemas/Title' patron: $ref: '#/components/schemas/Patron' patronColor: $ref: '#/components/schemas/PatronColor' required: - id - name PatronColor: type: integer description: 'Players can choose a color for their Patron wings. See [here for the color mappings](https://github.com/lichess-org/lila/blob/master/ui/lib/css/abstract/_patron-colors.scss). The presence of this field indicates the player is an active Patron. ' minimum: 1 maximum: 10 Title: type: string enum: - GM - WGM - IM - WIM - FM - WFM - NM - CM - WCM - WNM - LM - BOT description: only appears if the user is a titled player or a bot user Patron: type: boolean deprecated: true description: 'Use patronColor value instead to determine if player is a patron. ' Simul: type: object required: - id - host - name - fullName - variants - isCreated - isFinished - isRunning - nbApplicants - nbPairings properties: id: type: string host: type: object allOf: - $ref: '#/components/schemas/LightUser' - type: object properties: rating: type: integer provisional: type: boolean gameId: type: string online: type: boolean name: type: string fullName: type: string variants: type: array items: type: object properties: key: $ref: '#/components/schemas/VariantKey' icon: type: string name: type: string isCreated: type: boolean isFinished: type: boolean isRunning: type: boolean text: type: string estimatedStartAt: type: integer startedAt: type: integer finishedAt: type: integer nbApplicants: type: integer nbPairings: type: integer VariantKey: type: string enum: - standard - chess960 - crazyhouse - antichess - atomic - horde - kingOfTheHill - racingKings - threeCheck - fromPosition example: standard default: standard examples: simuls-getCurrentSimuls.json: value: pending: [] created: [] started: - id: XTZ0U0Z3 host: name: RohaRaj id: roharaj rating: 1174 provisional: false gameId: 7FRF62Up online: true name: RohaRaj fullName: RohaRaj simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: true isFinished: false text: '' nbApplicants: 0 nbPairings: 2 estimatedStartAt: 1778810586192 startedAt: 1778810586192 - id: MxZmjIcy host: name: sloppydogg title: IM id: sloppydogg rating: 2585 provisional: false gameId: fT2zPh6M online: true name: IM sloppydogg fullName: IM sloppydogg simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: true isFinished: false text: "Feel free to watch the stream while playing in the simul! :)\r\n\r\nhttps://www.twitch.tv/jludwig" nbApplicants: 0 nbPairings: 31 estimatedStartAt: 1778810189052 startedAt: 1778810189052 - id: ELUkHWFk host: name: StevenRamirez_UNTELS id: stevenramirez_untels rating: 2215 provisional: true gameId: Ey6my7Ij name: Silmultanea Gambito Steven fullName: Silmultanea Gambito Steven simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: true isFinished: false text: Gambito de Dama nbApplicants: 0 nbPairings: 3 estimatedStartAt: 1778809653537 startedAt: 1778809653537 finished: - id: zHvA9Fiy host: name: coachraven title: GM flair: nature.black-bird patron: true patronColor: 3 id: coachraven rating: 2089 provisional: true name: Caro Kann fullName: Caro Kann simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 15 estimatedStartAt: 1778805680207 startedAt: 1778805680207 finishedAt: 1778809853487 - id: PYaq1hb0 host: name: GMshooter96 title: IM flair: nature.crocodile id: gmshooter96 rating: 2517 provisional: true name: IM GMshooter96 fullName: IM GMshooter96 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 2 estimatedStartAt: 1778808607419 startedAt: 1778808607419 finishedAt: 1778809604812 - id: eplNIpsi host: name: lanchester1 title: GM id: lanchester1 rating: 2598 provisional: false name: GM Golizadeh fullName: GM Golizadeh simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Hello Everyone!\r\nWellcome to our Simul Exhibition!\r\n\r\n\r\none Request From all of you:\r\nplease follow us on our youtube channel before joing the simul.\r\nyour support is highly matter for us!\r\nhelp us to growth\r\n\r\nyoutube Channel: https://youtube.com/@kingprincesschess?si=uAYMq2hIxsq8HTnW" nbApplicants: 0 nbPairings: 7 estimatedStartAt: 1778801638585 startedAt: 1778801638585 finishedAt: 1778802566261 - id: m8b3e1wn host: name: AlvinAlcala title: NM flair: activity.trophy patron: true patronColor: 6 id: alvinalcala rating: 2540 provisional: true online: true name: NM AlvinAlcala fullName: NM AlvinAlcala simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 2 estimatedStartAt: 1778796906197 startedAt: 1778796906197 finishedAt: 1778797221350 - id: qEuh3zZh host: name: Mischuk_D title: IM id: mischuk_d rating: 2609 provisional: true name: MischukD fullName: MischukD simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "10 boards\r\nMy profile as a coach is - lichess.org/coach/Mischuk_D" nbApplicants: 0 nbPairings: 11 estimatedStartAt: 1778787525679 startedAt: 1778787525679 finishedAt: 1778789537744 - id: PjRuxC4a host: name: SLOM title: NM flair: nature.phoenix-bird id: slom rating: 2365 provisional: true name: Titled Players With Q and A fullName: Titled Players With Q and A simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "I am going to host a Q and A on my stream while I play against you guys in the simul. PLEASE join my stream and ask any questions that you have!\r\n\r\nI will be having titled player gests that will help me answer your questions!\r\n\r\nWe will start when we have 15-20 players!\r\n\r\nTo ask questions join the stream link down below to have us see your questions, both during and after the games:\r\n\r\nhttps://www.youtube.com/watch?v=QfaHy77_gwE" nbApplicants: 0 nbPairings: 22 estimatedStartAt: 1778776058108 startedAt: 1778776058108 finishedAt: 1778781437360 - id: 2gEc4pPy host: name: AndrCherr title: FM id: andrcherr rating: 2609 provisional: true name: Секреты при атаке - 1 fullName: Секреты при атаке - 1 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 2 estimatedStartAt: 1778779922611 startedAt: 1778779922611 finishedAt: 1778781322893 - id: njPlb4E6 host: name: Lance5500 title: LM patron: true patronColor: 10 id: lance5500 rating: 2569 provisional: false online: true name: Coach LM Lance5500 fullName: Coach LM Lance5500 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Chess coach: https://lichess.org/coach/Lance5500\r\nStudents reviews: https://lichess.org/forum/team-lance5500-chess-coach\r\nTemporary large discounts for the lessons packages \r\nFor lessons and other solid chess inquiries: direct message\r\n\r\nChampion: 11х Marathons, 13x Yearly, 9x Shields. Most trophies holder: 40x Marathon. \r\nPeak lichess ratings: 3052 bullet, 2801 blitz, 2815 rapid, 2622 classical\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_trophies.html\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_points.html\r\nCourses by @Kingscrusher-YouTube: https://kingscrusher.tv/chesscourses" nbApplicants: 0 nbPairings: 6 estimatedStartAt: 1778780828562 startedAt: 1778780828562 finishedAt: 1778781292565 - id: lGYMPUDC host: name: Zhigalko_Andrey title: GM patron: true patronColor: 10 id: zhigalko_andrey rating: 1500 provisional: true name: GM Zhigalko Andrey fullName: GM Zhigalko Andrey simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 22 estimatedStartAt: 1778773062345 startedAt: 1778773062345 finishedAt: 1778775165410 - id: l2flGovG host: name: Lance5500 title: LM patron: true patronColor: 10 id: lance5500 rating: 2569 provisional: false online: true name: Coach LM Lance5500 fullName: Coach LM Lance5500 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Chess coach: https://lichess.org/coach/Lance5500\r\nStudents reviews: https://lichess.org/forum/team-lance5500-chess-coach\r\nTemporary large discounts for the lessons packages \r\nFor lessons and other solid chess inquiries: direct message\r\n\r\nChampion: 11х Marathons, 13x Yearly, 9x Shields. Most trophies holder: 40x Marathon. \r\nPeak lichess ratings: 3052 bullet, 2801 blitz, 2815 rapid, 2622 classical\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_trophies.html\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_points.html\r\nCourses by @Kingscrusher-YouTube: https://kingscrusher.tv/chesscourses" nbApplicants: 0 nbPairings: 20 estimatedStartAt: 1778772647134 startedAt: 1778772647134 finishedAt: 1778773790997 - id: eoAq6MtS host: name: Lance5500 title: LM patron: true patronColor: 10 id: lance5500 rating: 2569 provisional: false online: true name: Coach LM Lance5500 fullName: Coach LM Lance5500 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Chess coach: https://lichess.org/coach/Lance5500\r\nStudents reviews: https://lichess.org/forum/team-lance5500-chess-coach\r\nTemporary large discounts for the lessons packages \r\nFor lessons and other solid chess inquiries: direct message\r\n\r\nChampion: 11х Marathons, 13x Yearly, 9x Shields. Most trophies holder: 40x Marathon. \r\nPeak lichess ratings: 3052 bullet, 2801 blitz, 2815 rapid, 2622 classical\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_trophies.html\r\nhttps://lichess.thijs.com/rankings/all/marathon/list_players_points.html\r\nCourses by @Kingscrusher-YouTube: https://kingscrusher.tv/chesscourses" nbApplicants: 0 nbPairings: 31 estimatedStartAt: 1778766268947 startedAt: 1778766268947 finishedAt: 1778768486350 - id: DrShld56 host: name: Zhigalko_Andrey title: GM patron: true patronColor: 10 id: zhigalko_andrey rating: 1500 provisional: true name: GM Zhigalko Andrey fullName: GM Zhigalko Andrey simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 20 estimatedStartAt: 1778764942036 startedAt: 1778764942036 finishedAt: 1778766902703 - id: 9GQx4afl host: name: Zhigalko_Andrey title: GM patron: true patronColor: 10 id: zhigalko_andrey rating: 1500 provisional: true name: GM Zhigalko Andrey fullName: GM Zhigalko Andrey simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 20 estimatedStartAt: 1778757533100 startedAt: 1778757533100 finishedAt: 1778759675099 - id: 2TnfPIHp host: name: Zhigalko_Andrey title: GM patron: true patronColor: 10 id: zhigalko_andrey rating: 1500 provisional: true name: GM Zhigalko Andrey fullName: GM Zhigalko Andrey simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 24 estimatedStartAt: 1778754680156 startedAt: 1778754680156 finishedAt: 1778757005773 - id: D0iXVniy host: name: Fighterman91 title: GM id: fighterman91 rating: 1500 provisional: true name: GM Fighterman91 fullName: GM Fighterman91 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Hey everyone!\r\n\r\nToday I’m taking on an exciting challenge\r\nI’ll be playing a 10-player simultaneous chess match! ️\r\n\r\nThink you can beat me? This is your chance\r\n\r\nAll the games will be uploaded on my YouTube channel with full analysis and commentary,\r\nso you can learn from your mistakes and improve your level.\r\n\r\nwww.youtube.com/@GMPouria\r\n\r\nMake sure to subscribe to the channel\r\nTurn on notifications so you don’t miss the videos\r\n\r\nLet’s see who can put up the best fight" nbApplicants: 0 nbPairings: 10 estimatedStartAt: 1778751147287 startedAt: 1778751147287 finishedAt: 1778753544695 - id: mUYiyykS host: name: Fighterman91 title: GM id: fighterman91 rating: 1500 provisional: true name: GM Fighterman91 fullName: GM Fighterman91 simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Hey everyone!\r\n\r\nToday I’m taking on an exciting challenge \r\nI’ll be playing a 10-player simultaneous chess match! ️\r\n\r\nThink you can beat me? This is your chance \r\n\r\n All the games will be uploaded on my YouTube channel with full analysis and commentary,\r\nso you can learn from your mistakes and improve your level.\r\n\r\nhttps://www.youtube.com/@GMPouria\r\n\r\n Make sure to subscribe to the channel\r\n Turn on notifications so you don’t miss the videos\r\n\r\nLet’s see who can put up the best fight" nbApplicants: 0 nbPairings: 4 estimatedStartAt: 1778749896527 startedAt: 1778749896527 finishedAt: 1778749987067 - id: EwCKTCPr host: name: Mischuk_D title: IM id: mischuk_d rating: 2609 provisional: true name: MischukD fullName: MischukD simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "10 boards\r\nMy profile as a coach is - lichess.org/coach/Mischuk_D" nbApplicants: 0 nbPairings: 10 estimatedStartAt: 1778746557064 startedAt: 1778746557064 finishedAt: 1778748857431 - id: 43o7A1bX host: name: Zhigalko_Andrey title: GM patron: true patronColor: 10 id: zhigalko_andrey rating: 1500 provisional: true name: GM Zhigalko Andrey fullName: GM Zhigalko Andrey simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 15 estimatedStartAt: 1778742288136 startedAt: 1778742288136 finishedAt: 1778744511442 - id: HsWQnJIn host: name: sloppydogg title: IM id: sloppydogg rating: 2585 provisional: false online: true name: IM sloppydogg fullName: IM sloppydogg simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: "Feel free to watch the stream while playing in the simul!!!\r\n\r\nhttps://www.twitch.tv/jludwig" nbApplicants: 0 nbPairings: 30 estimatedStartAt: 1778723706149 startedAt: 1778723706149 finishedAt: 1778728771027 - id: 0MrjJWPB host: name: MillerDominguez title: FM flair: nature.horse id: millerdominguez rating: 1264 provisional: false name: profe jaqueton fullName: profe jaqueton simul variants: - key: standard icon:  name: Standard isCreated: false isRunning: false isFinished: true text: '' nbApplicants: 0 nbPairings: 8 estimatedStartAt: 1778711278867 startedAt: 1778711278867 finishedAt: 1778712862386 securitySchemes: OAuth2: type: oauth2 description: 'Read [the introduction for how to make authenticated requests](#description/authentication). ' flows: authorizationCode: authorizationUrl: https://lichess.org/oauth tokenUrl: https://lichess.org/api/token scopes: preference:read: Read your preferences preference:write: Write your preferences email:read: Read your email address engine:read: Read your external engines engine:write: Create, update, delete your external engines 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 racer:write: Create and join puzzle races puzzle:read: Read puzzle activity puzzle:write: Write puzzle activity team:read: Read private team information team:write: Join, leave teams team:lead: Manage teams (kick members, send PMs) follow:read: Read followed players follow:write: Follow and unfollow other players 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](#tag/bot/POST/api/bot/account/upgrade) web:mod: Use moderator tools (within the bounds of your permissions)