diff options
Diffstat (limited to 'Sources/LichessClient/openapi.json')
| -rw-r--r-- | Sources/LichessClient/openapi.json | 15619 |
1 files changed, 15619 insertions, 0 deletions
diff --git a/Sources/LichessClient/openapi.json b/Sources/LichessClient/openapi.json new file mode 100644 index 0000000..5af0042 --- /dev/null +++ b/Sources/LichessClient/openapi.json @@ -0,0 +1,15619 @@ +{ + "openapi": "3.1.0", + "info": { + "version": "2.0.0", + "title": "Lichess.org API reference", + "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\nWelcome to the reference for the Lichess API! Lichess is free/libre,\nopen-source chess server powered by volunteers and donations.\n- Get help in the [Lichess Discord channel](https://discord.gg/lichess)\n- API demo app with OAuth2 login and gameplay: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)\n- API UI app with OAuth2 login and endpoint forms: [source](https://github.com/lichess-org/api-ui) / [website](https://lichess.org/api/ui)\n- [Contribute to this documentation on Github](https://github.com/lichess-org/api)\n- Check out [Lichess widgets to embed in your website](https://lichess.org/developers)\n- [Download all Lichess rated games](https://database.lichess.org/)\n- [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)\n- [Download all evaluated positions](https://database.lichess.org/#evals)\n\n## Endpoint\nAll requests go to `https://lichess.org` (unless otherwise specified).\n\n## Clients\n- [Python general API](https://github.com/lichess-org/berserk)\n- [MicroPython general API](https://github.com/mkomon/uberserk)\n- [Python general API - async](https://pypi.org/project/async-lichess-sdk)\n- [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)\n- [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)\n- [Java general API](https://github.com/tors42/chariot)\n- [JavaScript & TypeScript general API](https://github.com/devjiwonchoi/equine)\n\n## Rate limiting\nAll requests are rate limited using various strategies,\nto ensure the API remains responsive for everyone.\nOnly make one request at a time.\nIf you receive an HTTP response with a [429 status](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),\nplease wait a full minute before resuming API usage.\n\n## Streaming with ND-JSON\nSome 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.\n\nHere's a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.\n\n## Authentication\n### Which authentication method is right for me?\n[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)\n\n### Personal Access Token\nPersonal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.\n- [Generate a personal access token](https://lichess.org/account/oauth/token)\n- `curl https://lichess.org/api/account -H \"Authorization: Bearer {token}\"`\n- [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)\n\n### Authorization Code Flow with PKCE\nThe authorization code flow with PKCE allows your users to **login with Lichess**.\nLichess supports unregistered and public clients (no client authentication, choose any unique client id).\nThe only accepted code challenge method is `S256`.\nAccess tokens are long-lived (expect one year), unless they are revoked.\nRefresh tokens are not supported.\n\nSee the [documentation for the OAuth endpoints](#tag/OAuth) or\nthe [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.\n\n- [Demo app](https://lichess-org.github.io/api-demo/)\n- [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)\n- [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)\n- [Java example](https://github.com/tors42/lichess-oauth-pkce-app)\n- [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)\n\n#### Real life examples\n- [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))\n- [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))\n- [English Chess Federation](https://ecf.octoknight.com/)\n- [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)\n\n### Token format\nAccess tokens and authorization codes match `^[A-Za-z0-9_]+$`.\nThe length of tokens can be increased without notice. Make sure your application can handle at least 512 characters.\nBy convention tokens have a recognizable prefix, but do not rely on this.\n" + }, + "servers": [ + { + "url": "https://lichess.org" + } + ], + "tags": [ + { + "name": "Account", + "description": "Read and write account information and preferences.\n<https://lichess.org/account/preferences/game-display>\n" + }, + { + "name": "Users", + "description": "Access registered users on Lichess.\n<https://lichess.org/player>\n\n- Each user blog exposes an atom (RSS) feed, like <https://lichess.org/@/thibault/blog.atom>\n- User blogs mashup feed: https://lichess.org/blog/community.atom\n- User blogs mashup feed for a language: https://lichess.org/blog/community/fr.atom\n" + }, + { + "name": "Relations", + "description": "Access relations between users.\n" + }, + { + "name": "Games", + "description": "Access games played on Lichess.\n<https://lichess.org/games>\n" + }, + { + "name": "TV", + "description": "Access Lichess TV channels and games.\n<https://lichess.org/tv> & <https://lichess.org/games>\n" + }, + { + "name": "Puzzles", + "description": "Access Lichess [puzzle history and dashboard](https://lichess.org/training).\n\nOur collection of puzzles is in the public domain, you can [download it here](https://database.lichess.org/#puzzles).\nFor a list of our puzzle themes with their description, check out the [theme translation file](https://github.com/ornicar/lila/blob/master/translation/source/puzzleTheme.xml).\nThe daily puzzle can be [posted in your slack workspace](https://lichess.org/daily-puzzle-slack).\n" + }, + { + "name": "Teams", + "description": "Access and manage Lichess teams and their members.\n<https://lichess.org/team>\n" + }, + { + "name": "Board", + "description": "Play on Lichess with physical boards and third-party clients.\n Works with normal Lichess accounts. Engine play or assistance is [forbidden](https://lichess.org/page/fair-play).\n\n\n### Features\n - [Stream incoming chess moves](#operation/boardGameStream)\n - [Play chess moves](#operation/boardGameMove)\n - [Read](#operation/boardGameStream) and [write](#operation/boardGameChatPost) in the player and spectator chats\n - [Receive](#operation/apiStreamEvent), [create](#operation/challengeCreate) and [accept](#operation/challengeAccept) (or [decline](#operation/challengeDecline)) challenges\n - [Abort](#operation/boardGameAbort) and [resign](#operation/boardGameResign) games\n - Compatible with normal Lichess accounts\n\n \n### Restrictions\n - Engine assistance, or any kind of outside help, is [forbidden](https://lichess.org/page/fair-play)\n - Time controls: [Rapid, Classical and Correspondence](https://lichess.org/faq#time-controls) only.\n For direct challenges and games vs AI, Blitz is also possible.\n\n### Links\n - [Announcement](https://lichess.org/blog/XlRW5REAAB8AUJJ-/welcome-lichess-boards)\n - [Implementation example](https://github.com/lichess-org/api-demo) and [live demo](https://lichess-org.github.io/api-demo/)\n\n - [Certabo support](https://github.com/haklein/certabo-lichess)\n - [Lichs (play from command-line)](https://github.com/Cqsi/lichs)\n - [Lichess discord bot](https://top.gg/bot/707287095911120968)\n - [cli-chess](https://github.com/trevorbayless/cli-chess/)" + }, + { + "name": "Bot", + "description": "Play on Lichess as a bot. Allows engine play.\n Read the [blog post announcement of lichess bots](https://lichess.org/blog/WvDNticAAMu_mHKP/welcome-lichess-bots).\n\n Only works with [Bot accounts](#operation/botAccountUpgrade).\n\n\n### Features\n - [Stream incoming chess moves](#operation/botGameStream)\n - [Play chess moves](#operation/botGameMove)\n - [Read](#operation/botGameStream) and [write](#operation/botGameChat) in the player and spectator chats\n - [Receive](#operation/apiStreamEvent), [create](#operation/challengeCreate) and [accept](#operation/challengeAccept) (or [decline](#operation/challengeDecline)) challenges\n - [Abort](#operation/botGameAbort) and [resign](#operation/botGameResign) games\n - Engine assistance is [allowed](https://lichess.org/page/fair-play)\n\n### Restrictions\n - Bots can only play challenge games: pools and tournaments are off-limits\n - Bots cannot play UltraBullet (¼+0) because it requires making too many requests. But 0+1 and ½+0 are allowed.\n - Bots must follow [Lichess TOS](https://lichess.org/terms-of-service) specifically Sandbagging, Constant Aborting, Boosting, etc\n - Bot devs are advised to make their Bots play casual only when testing their Bots logic and to avoid breaking Lichess TOS.\n\n### Integrations\n - [Python3 lichess-bot](https://github.com/lichess-bot-devs/lichess-bot) (official)\n - [Python3 lichess UCI bot](https://github.com/Torom/BotLi)\n - [JavaScript bot-o-tron](https://github.com/tailuge/bot-o-tron)\n - [Golang lichess-bot](https://github.com/dolegi/lichess-bot)\n - [Electronic Chessboard](http://www.oliviermercier.com/res/projects/chessboard/) - Yours? Please make [an issue or pull request](https://github.com/lichess-org/api).\n\n### Links\n - [Announcement](https://lichess.org/blog/WvDNticAAMu_mHKP/welcome-lichess-bots)\n - Join the [Lichess Bots team](https://lichess.org/team/lichess-bots) with your bot account\n - [Get help in the discord channel](https://discord.gg/quwueFd)\n - Watch [Lichess Bot TV](https://lichess.org/tv/bot)" + }, + { + "name": "Challenges", + "description": "Send and receive challenges to play.\n\nTo create a lot of challenges, consider [bulk pairing](#operation/bulkPairingCreate) instead.\n" + }, + { + "name": "Bulk pairings", + "description": "Create many games for other players.\n\nThese endpoints are intended for tournament organisers.\n" + }, + { + "name": "Arena tournaments", + "description": "Access Arena tournaments played on Lichess.\n[Official Arena tournaments](https://lichess.org/tournament) are maintained by Lichess,\nbut you can [create your own Arena tournaments](https://lichess.org/tournament/new) as well.\n" + }, + { + "name": "Swiss tournaments", + "description": "Access Swiss tournaments played on Lichess.\n[Read more about Swiss tournaments.](https://lichess.org/swiss).\n" + }, + { + "name": "Simuls", + "description": "Access simuls played on Lichess.\n<https://lichess.org/simul>\n" + }, + { + "name": "Studies", + "description": "Access Lichess studies.\n<https://lichess.org/study>\n" + }, + { + "name": "Messaging", + "description": "Private messages with other players.\n<https://lichess.org/inbox>\n" + }, + { + "name": "Broadcasts", + "description": "Relay chess events on Lichess.\n[Official broadcasts](https://lichess.org/broadcast) are maintained by Lichess,\nbut you can [create your own broadcasts](https://lichess.org/broadcast/new) to cover any live game or chess event.\nYou will need to publish PGN on a public URL so that Lichess can pull updates from it.\nAlternatively, you can push PGN updates to Lichess using [this API endpoint](#tag/Broadcasts/operation/broadcastPush).\n\nBroadcasts are organized in tournaments, which have several rounds, which have several games.\nYou must first create a tournament, then you can add rounds to them.\n" + }, + { + "name": "Analysis", + "description": "Access Lichess cloud evaluations database.\n<https://lichess.org/analysis>\n" + }, + { + "name": "External engine", + "description": "**This API is in alpha and subject to change.**\n\nUse or provide external engine analysis.\n\nExternal engines can provide analysis on pages like the\n[analysis board](https://lichess.org/analysis), running as a service\noutside of the browser, or even on a different machine.\n" + }, + { + "name": "Opening Explorer", + "description": "Lookup positions from the [Lichess opening explorer](https://lichess.org/analysis#explorer).\n\nRuns <https://github.com/niklasf/lila-openingexplorer>.\n\n**The endpoint hostname is not lichess.org but explorer.lichess.ovh.**\n" + }, + { + "name": "Tablebase", + "description": "Lookup positions from the [Lichess tablebase server](https://lichess.org/blog/W3WeMyQAACQAdfAL/7-piece-syzygy-tablebases-are-complete).\n\n**The endpoint hostname is not lichess.org but tablebase.lichess.ovh.**\n" + }, + { + "name": "OAuth", + "description": "Obtaining and revoking OAuth tokens.\n\n[Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md).\n" + } + ], + "paths": { + "/api/users/status": { + "get": { + "operationId": "apiUsersStatus", + "summary": "Get real-time users status", + "description": "Read the `online`, `playing` and `streaming` flags of several users.\nThis API is very fast and cheap on lichess side.\nSo you can call it quite often (like once every 5 seconds).\nUse it to track players and know when they're connected on lichess and playing games.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "ids", + "required": true, + "description": "User IDs separated by commas. Up to 100 IDs.", + "schema": { + "type": "string" + }, + "example": "aliquantus,chess-network,lovlas" + }, + { + "in": "query", + "name": "withGameIds", + "required": false, + "description": "Also return the ID of the game being played, if any, for each player, in a `playingId` field.\nDefaults to `false` to preserve server resources.\n", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "The list of users and their respective statuses.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "title": { + "type": "string" + }, + "online": { + "type": "boolean" + }, + "playing": { + "type": "boolean" + }, + "streaming": { + "type": "boolean" + }, + "patron": { + "type": "boolean" + } + }, + "required": [ + "id", + "name" + ] + }, + "example": [ + { + "id": "aliquantus", + "name": "Aliquantus" + }, + { + "id": "chess-network", + "name": "Chess-Network", + "title": "NM", + "online": true, + "playing": true, + "streaming": true, + "patron": true + } + ] + } + } + } + } + } + } + }, + "/api/player": { + "get": { + "operationId": "player", + "summary": "Get all top 10", + "tags": [ + "Users" + ], + "security": [], + "description": "Get the top 10 players for each speed and variant.\nSee <https://lichess.org/player>.\n", + "responses": { + "200": { + "description": "The list of variants with their respective top players.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Top10s" + } + } + } + } + } + } + }, + "/api/player/top/{nb}/{perfType}": { + "get": { + "operationId": "playerTopNbPerfType", + "summary": "Get one leaderboard", + "tags": [ + "Users" + ], + "security": [], + "description": "Get the leaderboard for a single speed or variant (a.k.a. `perfType`).\nThere is no leaderboard for correspondence or puzzles.\nSee <https://lichess.org/player/top/200/bullet>.\n", + "parameters": [ + { + "in": "path", + "name": "nb", + "description": "How many users to fetch", + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 200, + "example": 100 + }, + "required": true + }, + { + "in": "path", + "name": "perfType", + "description": "The speed or variant", + "schema": { + "type": "string", + "example": "bullet", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck" + ] + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of top players for the variant.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/vnd.lichess.v3+json": { + "schema": { + "$ref": "#/components/schemas/Leaderboard" + } + } + } + } + } + } + }, + "/api/user/{username}": { + "get": { + "operationId": "apiUser", + "summary": "Get user public data", + "description": "Read public data of a user.\n", + "tags": [ + "Users" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "trophies", + "description": "Include user trophies", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The information of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/user/{username}/rating-history": { + "get": { + "operationId": "apiUserRatingHistory", + "summary": "Get rating history of a user", + "description": "Read rating history of a user, for all perf types.\nThere is at most one entry per day.\nFormat of an entry is `[year, month, day, rating]`.\n`month` starts at zero (January).\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The rating history of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RatingHistory" + } + } + } + } + } + } + }, + "/api/user/{username}/perf/{perf}": { + "get": { + "operationId": "apiUserPerf", + "summary": "Get performance statistics of a user", + "description": "Read performance statistics of a user, for a single performance.\nSimilar to the [performance pages on the website](https://lichess.org/@/thibault/perf/bullet).\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "path", + "name": "perf", + "schema": { + "$ref": "#/components/schemas/PerfType" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The performance statistics of the user", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PerfStat" + } + } + } + } + } + } + }, + "/api/user/{username}/activity": { + "get": { + "operationId": "apiUserActivity", + "summary": "Get user activity", + "description": "Read data to generate the activity feed of a user.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The activity feed of the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": "https://gist.github.com/ornicar/0ee2d2427cb74ed1a35e86f5ba09fabc" + } + } + } + } + } + }, + "/api/puzzle/daily": { + "get": { + "operationId": "apiPuzzleDaily", + "summary": "Get the daily puzzle", + "description": "Get the daily Lichess puzzle in JSON format.\nAlternatively, you can [post it in your slack workspace](https://lichess.org/daily-puzzle-slack).\n", + "tags": [ + "Puzzles" + ], + "security": [], + "responses": { + "200": { + "description": "The daily puzzle.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleAndGame" + } + } + } + } + } + } + }, + "/api/puzzle/{id}": { + "get": { + "operationId": "apiPuzzleId", + "summary": "Get a puzzle by its ID", + "description": "Get a single Lichess puzzle in JSON format.", + "tags": [ + "Puzzles" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The puzzle ID", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The requested puzzle.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleAndGame" + } + } + } + } + } + } + }, + "/api/puzzle/activity": { + "get": { + "operationId": "apiPuzzleActivity", + "summary": "Get your puzzle activity", + "description": "Download your puzzle activity in [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\nPuzzle activity is sorted by reverse chronological order (most recent first)\nWe recommend streaming the response, for it can be very long.\n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "puzzle:read" + ] + } + ], + "parameters": [ + { + "in": "query", + "name": "max", + "description": "How many entries to download. Leave empty to download all activity.", + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "in": "query", + "name": "before", + "description": "Download entries before this timestamp. Defaults to now. Use `before` and `max` for pagination.", + "schema": { + "type": "integer", + "minimum": 1356998400070 + } + } + ], + "responses": { + "200": { + "description": "The puzzle activity of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/PuzzleRoundJson" + } + } + } + } + } + } + }, + "/api/puzzle/dashboard/{days}": { + "get": { + "operationId": "apiPuzzleDashboard", + "summary": "Get your puzzle dashboard", + "description": "Download your [puzzle dashboard](https://lichess.org/training/dashboard/30/dashboard) as JSON.\nAlso includes all puzzle themes played, with aggregated results.\nAllows re-creating the [improvement/strengths](https://lichess.org/training/dashboard/30/improvementAreas) interfaces.\n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "puzzle:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "days", + "required": true, + "description": "How many days to look back when aggregating puzzle results. 30 is sensible.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The puzzle dashboard of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleDashboardJson" + } + } + } + } + } + } + }, + "/api/storm/dashboard/{username}": { + "get": { + "operationId": "apiStormDashboard", + "summary": "Get the storm dashboard of a player", + "description": "Download the [storm dashboard](https://lichess.org/storm/dashboard/mrbasso) of any player as JSON.\nContains the aggregated highscores, and the history of storm runs aggregated by days.\nUse `?days=0` if you only care about the highscores.\n", + "tags": [ + "Puzzles" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "Username of the player", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "days", + "description": "How many days of history to return", + "schema": { + "type": "integer", + "minimum": 0, + "maximum": 365, + "default": 30 + } + } + ], + "responses": { + "200": { + "description": "The storm dashboard of a player.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StormDashboardJson" + } + } + } + } + } + } + }, + "/api/racer": { + "post": { + "operationId": "racerPost", + "summary": "Create and join a puzzle race", + "description": "Create a new private [puzzle race](https://lichess.org/racer).\nThe Lichess user who creates the race must join the race page,\nand manually start the race when enough players have joined.\n- <https://lichess.org/racer>\n", + "tags": [ + "Puzzles" + ], + "security": [ + { + "OAuth2": [ + "racer:write" + ] + } + ], + "responses": { + "200": { + "description": "The new puzzle race.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PuzzleRaceJson" + } + } + } + } + } + } + }, + "/api/users": { + "post": { + "operationId": "apiUsers", + "summary": "Get users by ID", + "tags": [ + "Users" + ], + "security": [], + "description": "Get up to 300 users by their IDs. Users are returned in the same order as the IDs.\nThe method is `POST` to allow a longer list of IDs to be sent in the request body.\nPlease do not try to download all the Lichess users with this endpoint, or any other endpoint.\nAn API is not a way to fully export a website. We do not provide a full download of the Lichess users.\nThis endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day.\n", + "requestBody": { + "description": "User IDs separated by commas.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "aliquantus,chess-network,lovlas" + } + } + }, + "responses": { + "200": { + "description": "The list of users.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + } + } + } + } + } + } + }, + "/api/account": { + "get": { + "operationId": "accountMe", + "summary": "Get my profile", + "description": "Public information about the logged in user.\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [] + } + ], + "responses": { + "200": { + "description": "The public information about the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/account/email": { + "get": { + "operationId": "accountEmail", + "summary": "Get my email address", + "description": "Read the email address of the logged in user.\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "email:read" + ] + } + ], + "responses": { + "200": { + "description": "The email address of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "email": { + "type": "string" + } + }, + "example": { + "email": "abathur@mail.org" + } + } + } + } + } + } + } + }, + "/api/account/preferences": { + "get": { + "operationId": "account", + "summary": "Get my preferences", + "description": "Read the preferences of the logged in user.\n- <https://lichess.org/account/preferences/game-display>\n- <https://github.com/ornicar/lila/blob/master/modules/pref/src/main/Pref.scala>\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:read" + ] + } + ], + "responses": { + "200": { + "description": "The preferences of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "prefs": { + "$ref": "#/components/schemas/UserPreferences" + }, + "language": { + "type": "string", + "example": "en-GB" + } + } + } + } + } + } + } + } + }, + "/api/account/kid": { + "get": { + "operationId": "accountKid", + "summary": "Get my kid mode status", + "description": "Read the kid mode status of the logged in user.\n- <https://lichess.org/account/kid>\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:read" + ] + } + ], + "responses": { + "200": { + "description": "The kid mode status of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "kid": { + "type": "boolean" + } + }, + "example": { + "kid": false + } + } + } + } + } + } + }, + "post": { + "operationId": "accountKidPost", + "summary": "Set my kid mode status", + "description": "Set the kid mode status of the logged in user.\n- <https://lichess.org/account/kid>\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [ + "preference:write" + ] + } + ], + "parameters": [ + { + "in": "query", + "name": "v", + "required": true, + "description": "Kid mode status", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "200": { + "description": "The kid mode status was set successfully for the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/timeline": { + "get": { + "operationId": "timeline", + "summary": "Get my timeline", + "description": "Get the timeline events of the logged in user.\n", + "tags": [ + "Account" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "query", + "name": "since", + "description": "Show events since this timestamp.", + "schema": { + "type": "integer", + "minimum": 1356998400070 + } + }, + { + "in": "query", + "name": "nb", + "description": "Max number of events to fetch.", + "schema": { + "type": "integer", + "default": 15, + "minimum": 1, + "maximum": 30 + } + } + ], + "responses": { + "200": { + "description": "The events in the timeline of the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Timeline" + } + } + } + } + } + } + }, + "/game/export/{gameId}": { + "get": { + "operationId": "gamePgn", + "summary": "Export one game", + "description": "Download one game in either PGN or JSON format.\nOngoing 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.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "gameId", + "description": "The game ID (8 characters).", + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "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.\nExample: `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)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: <https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt>\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The game representation.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/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.\nAvailable in either PGN or JSON format.\nOngoing 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.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "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.\nExample: `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)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: <https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt>\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The ongoing (or last) game of a user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/games/user/{username}": { + "get": { + "operationId": "apiGamesUser", + "summary": "Export games of a user", + "description": "Download all games of any user in PGN or [ndjson](#section/Introduction/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](#section/Introduction/Authentication) request: 30 games per second\n - Authenticated, downloading your own games: 60 games per second\n", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "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.\n \nMultiple perf types can be specified, separated by a comma.\n \nExample: blitz,rapid,classical", + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/PerfType" + }, + { + "default": null + } + ] + } + }, + { + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "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.\nExample: `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)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "lastFen", + "description": "Include the FEN notation of the last position of the game.\nThe response type must be set to `application/x-ndjson` by the request `Accept` header.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: <https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt>\n", + "schema": { + "type": "string" + } + }, + { + "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-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/games/export/_ids": { + "post": { + "operationId": "gamesExportIds", + "summary": "Export games by IDs", + "description": "Download games by IDs in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request `Accept` header.\nGames are sorted by reverse chronological order (most recent first)\nThe method is `POST` so a longer list of IDs can be sent in the request body.\n300 IDs can be submitted.\nOngoing 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.\n", + "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": [ + { + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "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.\nExample: `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)`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "players", + "description": "URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN.\nExample: <https://gist.githubusercontent.com/ornicar/6bfa91eb61a2dcae7bcd14cce1b2a4eb/raw/768b9f6cc8a8471d2555e47ba40fb0095e5fba37/gistfile1.txt>\n", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The representation of the games.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/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.\nOnly games where **both players** are part of the list are included.\nThe stream emits an event each time a game is started or finished.\nTo also get all current ongoing games at the beginning of the stream, use the `withCurrentGames` flag.\nGames are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nMaximum number of users: 300.\nThe method is `POST` so a longer list of IDs can be sent in the request body.\n", + "tags": [ + "Games" + ], + "security": [], + "requestBody": { + "description": "Up to 300 user IDs separated by commas.\nExample: `aliquantus,chess-network,lovlas`\n", + "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.\nThe stream first outputs the games that already exists, then emits an event each time a game is started or finished.\nGames are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nMaximum number of games: 500 for anonymous requests, or 1000 for [OAuth2 authenticated](#section/Introduction/Authentication) requests.\nWhile the stream is open, it is possible to [add new game IDs to watch](#operation/gamesByIdsAdd).\n", + "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.\nExample: `gameId01,gameId02,gameId03`\n", + "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](#operation/gamesByIds) to watch.\nThe stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "streamId", + "schema": { + "type": "string", + "description": "The stream ID you used to [create the stream](#operation/gamesByIds).", + "example": "myAppName-someRandomId" + }, + "required": true + } + ], + "requestBody": { + "description": "Up to 500 or 1000 game IDs separated by commas.\nExample: `gameId04,gameId05,gameId06`\n", + "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.\nReal-time and correspondence games are included.\nThe most urgent games are listed first.\n", + "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": { + "example": { + "nowPlaying": [ + { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "rating": 1790, + "username": "Philippe" + }, + "perf": "correspondence", + "rated": false, + "secondsLeft": 1209600, + "source": "friend", + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + } + } + ] + } + } + } + } + } + } + } + }, + "/api/stream/game/{id}": { + "get": { + "operationId": "streamGame", + "summary": "Stream moves of a game", + "description": "Stream positions and moves of any ongoing game, in [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nA description of the game is sent as a first message.\nThen a message is sent each time a move is played.\nFinally a description of the game is sent when it finishes, and the stream is closed.\nOngoing 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.\nNo more than 8 game streams can be opened at the same time from the same IP address.\n", + "tags": [ + "Games" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "example": "LuGQwhBb" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the game moves.", + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/MoveStream" + } + } + } + } + } + } + }, + "/api/import": { + "post": { + "operationId": "gameImport", + "summary": "Import one game", + "description": "Import a game from PGN. See <https://lichess.org/paste>.\nRate limiting: 200 games per hour for OAuth requests, 100 games per hour for anonymous requests.\nTo broadcast ongoing games, consider [pushing to a broadcast instead](#operation/broadcastPush).\nTo analyse a position or a line, just construct an analysis board URL:\n[https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+](https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+)\n", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "requestBody": { + "description": "A single game to import", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "pgn": { + "type": "string", + "description": "The PGN. It can contain only one game. Most standard tags are supported." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The game was successfully imported.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "id": "R6iLjwz5", + "url": "https://lichess.org/R6iLjwz5" + } + } + } + } + } + } + } + }, + "/api/games/export/imports": { + "get": { + "operationId": "apiImportedGamesUser", + "summary": "Export your imported games", + "description": "Download all games imported by you. Games are exported in PGN format.", + "tags": [ + "Games" + ], + "security": [ + { + "OAuth2": [] + } + ], + "responses": { + "200": { + "description": "Imported games in PGN format", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + } + } + } + } + } + }, + "/api/tv/channels": { + "get": { + "operationId": "tvChannels", + "summary": "Get current TV games", + "description": "Get basic info about the best games being played for each speed and variant,\nbut also computer games and bot games.\nSee [lichess.org/tv](https://lichess.org/tv).\n", + "tags": [ + "TV" + ], + "security": [], + "responses": { + "200": { + "description": "The list of games being played for each speed and variant.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "bot": { + "user": { + "id": "leelachess", + "name": "LeelaChess", + "title": "BOT" + }, + "rating": 2660, + "gameId": "Zznv9MIl", + "color": "black" + }, + "blitz": { + "user": { + "id": "lekkerkortook", + "name": "LekkerKortOok" + }, + "rating": 2603, + "gameId": "hTJ4v7Mp", + "color": "black" + }, + "racingKings": { + "user": { + "id": "chesslo21", + "name": "chesslo21" + }, + "rating": 2123, + "gameId": "lgCDl5Of", + "color": "white" + }, + "ultraBullet": { + "user": { + "id": "farmville", + "name": "Farmville" + }, + "rating": 2338, + "gameId": "NEY6OQ32", + "color": "white" + }, + "bullet": { + "user": { + "id": "nurmibrah", + "name": "nurmiBrah" + }, + "rating": 2499, + "gameId": "5LgyE516", + "color": "black" + }, + "classical": { + "user": { + "id": "holden_m_j_thomas", + "name": "Holden_M_J_Thomas" + }, + "rating": 1806, + "gameId": "k3oLby6N", + "color": "white" + }, + "threeCheck": { + "user": { + "id": "pepellou", + "name": "pepellou", + "patron": true + }, + "rating": 1978, + "gameId": "Og5RCvmu", + "color": "black" + }, + "antichess": { + "user": { + "id": "maria-bakkar", + "name": "maria-bakkar" + }, + "rating": 2103, + "gameId": "toCr41yx", + "color": "black" + }, + "computer": { + "user": { + "id": "oh_my_goat_im_so_bat", + "name": "oh_my_goat_Im_so_bat" + }, + "rating": 2314, + "gameId": "TkI4qZxu", + "color": "black" + }, + "horde": { + "user": { + "id": "habitualchess", + "name": "HabitualChess" + }, + "rating": 1803, + "gameId": "oMofN63H", + "color": "white" + }, + "rapid": { + "user": { + "id": "denpayd", + "name": "DenpaYD" + }, + "rating": 2289, + "gameId": "IcWOl8ee" + }, + "atomic": { + "user": { + "id": "meetyourdemise", + "name": "MeetYourDemise" + }, + "rating": 2210, + "gameId": "tvMxtCMN", + "color": "white" + }, + "crazyhouse": { + "user": { + "id": "mathace", + "name": "mathace" + }, + "rating": 2397, + "gameId": "i3gTZlUb", + "color": "black" + }, + "chess960": { + "user": { + "id": "voja_7", + "name": "voja_7" + }, + "rating": 1782, + "gameId": "lrXLcedu", + "color": "white" + }, + "kingOfTheHill": { + "user": { + "id": "nadime", + "name": "Nadime" + }, + "rating": 1500, + "gameId": "DsQn8aEV", + "color": "white" + }, + "topRated": { + "user": { + "id": "lekkerkortook", + "name": "LekkerKortOok" + }, + "rating": 2603, + "gameId": "hTJ4v7Mp", + "color": "black" + } + } + } + } + } + } + } + } + }, + "/api/tv/feed": { + "get": { + "operationId": "tvFeed", + "summary": "Stream current TV game", + "description": "Stream positions and moves of the current [TV game](https://lichess.org/tv) in [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nA summary of the game is sent as a first message, and when the featured game changes.\nTry it with `curl https://lichess.org/api/tv/feed`.\n", + "tags": [ + "TV" + ], + "security": [], + "responses": { + "200": { + "description": "The stream of the current TV game.", + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/TvFeed" + }, + "examples": { + "first line": { + "$ref": "#/components/examples/tvFeedFirst" + }, + "subsequent lines": { + "$ref": "#/components/examples/tvFeedFen" + } + } + } + } + } + } + } + }, + "/api/tv/{channel}/feed": { + "get": { + "operationId": "tvChannelFeed", + "summary": "Stream current TV game of a TV channel", + "description": "Stream positions and moves of the current [TV game](https://lichess.org/tv) of a TV channel in [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nA summary of the game is sent as a first message, and when the featured game changes.\nTry it with `curl https://lichess.org/api/tv/rapid/feed`.\n", + "tags": [ + "TV" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "channel", + "description": "The name of the channel in camel case.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the current TV game of a TV channel.", + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/TvFeed" + }, + "examples": { + "first line": { + "$ref": "#/components/examples/tvFeedFirst" + }, + "subsequent lines": { + "$ref": "#/components/examples/tvFeedFen" + } + } + } + } + } + } + } + }, + "/api/tv/{channel}": { + "get": { + "operationId": "tvChannelGames", + "summary": "Get best ongoing games of a TV channel", + "description": "Get a list of ongoing games for a given TV channel. Similar to [lichess.org/games](https://lichess.org/games).\nAvailable in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request `Accept` header.\n", + "tags": [ + "TV" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "channel", + "description": "The name of the channel in camel case.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Number of games to fetch.", + "schema": { + "type": "number", + "default": 10, + "minimum": 1, + "maximum": 30 + } + }, + { + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The representation of the games.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/tournament": { + "get": { + "operationId": "apiTournament", + "summary": "Get current tournaments", + "description": "Get recently finished, ongoing, and upcoming tournaments.\nThis API is used to display the [Lichess tournament schedule](https://lichess.org/tournament).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "responses": { + "200": { + "description": "The list of current tournaments.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournaments" + } + } + } + } + } + }, + "post": { + "operationId": "apiTournamentPost", + "summary": "Create a new Arena tournament", + "description": "Create a public or private Arena tournament.\nThis endpoint mirrors the form on <https://lichess.org/tournament/new>.\nYou can create up to 12 public tournaments per day, or 24 private tournaments.\nA team battle can be created by specifying the `teamBattleByTeam` argument.\nAdditional restrictions:\n - clockTime + clockIncrement > 0\n - 15s and 0+1 variant tournaments cannot be rated\n - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clockTime": { + "type": "number", + "description": "Clock initial time in minutes", + "example": 2, + "enum": [ + 0, + 0.25, + 0.5, + 0.75, + 1, + 1.5, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "clockIncrement": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "enum": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "minutes": { + "type": "integer", + "description": "How long the tournament lasts, in minutes", + "example": 60, + "enum": [ + 20, + 25, + 30, + 35, + 40, + 45, + 50, + 55, + 60, + 70, + 80, + 90, + 100, + 110, + 120, + 150, + 180, + 210, + 240, + 270, + 300, + 330, + 360, + 420, + 480, + 540, + 600, + 720 + ] + }, + "waitMinutes": { + "type": "integer", + "description": "How long to wait before starting the tournament, from now, in minutes", + "default": 5, + "enum": [ + 1, + 2, + 3, + 5, + 10, + 15, + 20, + 30, + 45, + 60 + ] + }, + "startDate": { + "type": "integer", + "description": "Timestamp (in milliseconds) to start the tournament at a given date and time. Overrides the `waitMinutes` setting" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "berserkable": { + "type": "boolean", + "description": "Whether the players can use berserk. Only allowed if clockIncrement <= clockTime * 2", + "default": true + }, + "streakable": { + "type": "boolean", + "description": "After 2 wins, consecutive wins grant 4 points instead of 2.", + "default": true + }, + "hasChat": { + "type": "boolean", + "description": "Whether the players can discuss in a chat", + "default": true + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "password": { + "type": "string", + "description": "Make the tournament private, and restrict access with a password.\nYou can also [generate user-specific entry codes](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code)\nbased on this password.\n" + }, + "teamBattleByTeam": { + "type": "string", + "description": "Set the ID of a team you lead to create a team battle.\nThe other teams can be added using the [team battle edit endpoint](#operation/apiTournamentTeamBattlePost).\n" + }, + "conditions.teamMember.teamId": { + "type": "string", + "description": "Restrict entry to members of a team.\nThe teamId is the last part of a team URL, e.g. `https://lichess.org/team/coders` has teamId = `coders`.\nLeave empty to let everyone join the tournament.\nDo not use this to create team battles, use `teamBattleByTeam` instead.\n" + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "enum": [ + 0, + 5, + 10, + 15, + 20, + 30, + 40, + 50, + 75, + 100, + 150, + 200 + ] + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clockTime", + "clockIncrement", + "minutes" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Arena tournament has been successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournamentVariantIsKey" + } + } + } + }, + "400": { + "description": "The creation of the Arena tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "get": { + "operationId": "tournament", + "summary": "Get info about an Arena tournament", + "description": "Get detailed info about recently finished, current, or upcoming tournament's duels, player standings, and other info.\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "page", + "description": "Specify which page of player standings to view.", + "schema": { + "type": "number", + "example": 1, + "default": 1, + "minimum": 1, + "maximum": 200 + } + } + ], + "responses": { + "200": { + "description": "The information of the Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournamentVariantIsKey" + } + } + } + } + } + }, + "post": { + "operationId": "apiTournamentUpdate", + "summary": "Update an Arena tournament", + "description": "Update an Arena tournament.\nBe mindful not to make important changes to ongoing tournaments.\nCan be used to update a team battle.\nAdditional restrictions:\n - clockTime + clockIncrement > 0\n - 15s and 0+1 variant tournaments cannot be rated\n - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clockTime": { + "type": "number", + "description": "Clock initial time in minutes", + "example": 2, + "enum": [ + 0, + 0.25, + 0.5, + 0.75, + 1, + 1.5, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "clockIncrement": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "enum": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 10, + 15, + 20, + 25, + 30, + 40, + 50, + 60 + ] + }, + "minutes": { + "type": "integer", + "description": "How long the tournament lasts, in minutes", + "example": 60, + "enum": [ + 20, + 25, + 30, + 35, + 40, + 45, + 50, + 55, + 60, + 70, + 80, + 90, + 100, + 110, + 120, + 150, + 180, + 210, + 240, + 270, + 300, + 330, + 360, + 420, + 480, + 540, + 600, + 720 + ] + }, + "waitMinutes": { + "type": "integer", + "description": "How long to wait before starting the tournament, from now, in minutes", + "default": 5, + "enum": [ + 1, + 2, + 3, + 5, + 10, + 15, + 20, + 30, + 45, + 60 + ] + }, + "startDate": { + "type": "integer", + "description": "Timestamp (in milliseconds) to start the tournament at a given date and time. Overrides the `waitMinutes` setting" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "berserkable": { + "type": "boolean", + "description": "Whether the players can use berserk. Only allowed if clockIncrement <= clockTime * 2", + "default": true + }, + "streakable": { + "type": "boolean", + "description": "After 2 wins, consecutive wins grant 4 points instead of 2.", + "default": true + }, + "hasChat": { + "type": "boolean", + "description": "Whether the players can discuss in a chat", + "default": true + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "password": { + "type": "string", + "description": "Make the tournament private, and restrict access with a password" + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "enum": [ + 0, + 5, + 10, + 15, + 20, + 30, + 40, + 50, + 75, + 100, + 150, + 200 + ] + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clockTime", + "clockIncrement", + "minutes" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Arena tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournamentVariantIsKey" + } + } + } + }, + "400": { + "description": "The update of the Arena tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/join": { + "post": { + "operationId": "apiTournamentJoin", + "summary": "Join an Arena tournament", + "description": "Join an Arena tournament, possibly with a password and/or a team.\nAlso unpauses if you had previously [paused](#operation/apiTournamentWithdraw) the tournament.\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "You may need these depending on the tournament to join", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "password": { + "type": "string", + "description": "The tournament password, if one is required.\nCan also be a [user-specific entry code](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code)\ngenerated and shared by the organizer.\n" + }, + "team": { + "type": "string", + "description": "The team to join the tournament with, for team battle tournaments" + }, + "pairMeAsap": { + "type": "boolean", + "default": false, + "description": "If the tournament is started, attempt to pair the user,\neven if they are not connected to the tournament page.\nThis expires after one minute, to avoid pairing a user who is long gone.\nYou may call \"join\" again to extend the waiting.\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The tournament was successfully joined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Joining the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/withdraw": { + "post": { + "operationId": "apiTournamentWithdraw", + "summary": "Pause or leave an Arena tournament", + "description": "Leave a future Arena tournament, or take a break on an ongoing Arena tournament.\nIt's possible to join again later. Points and streaks are preserved.\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully paused or left.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Pausing/leaving the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/terminate": { + "post": { + "operationId": "apiTournamentTerminate", + "summary": "Terminate an Arena tournament", + "description": "Terminate an Arena tournament\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully terminated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Terminating the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/team-battle/{id}": { + "post": { + "operationId": "apiTournamentTeamBattlePost", + "summary": "Update a team battle", + "description": "Set the teams and number of leaders of a team battle.\nTo update the other attributes of a team battle, use the [tournament update endpoint](#operation/apiTournamentUpdate).\n", + "tags": [ + "Arena tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID (8 characters)..", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "teams": { + "type": "string", + "description": "All team IDs of the team battle, separated by commas.\nMake sure to always send the full list.\nTeams that are not in the list will be removed from the team battle.\nExample: `coders,zhigalko_sergei-fan-club,hhSwTKZv`\n" + }, + "nbLeaders": { + "type": "integer", + "description": "Number team leaders per team." + } + }, + "required": [ + "teams", + "nbLeaders" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The team battle tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArenaTournamentVariantIsKey" + } + } + } + }, + "400": { + "description": "The update of the team battle tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/tournament/{id}/games": { + "get": { + "operationId": "gamesByTournament", + "summary": "Export games of an Arena tournament", + "description": "Download games of a tournament in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\nGames are sorted by reverse chronological order (most recent first).\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "player", + "description": "Only games of a particular player. Leave empty to fetch games of all players.", + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of games of an Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/tournament/{id}/results": { + "get": { + "operationId": "resultsByTournament", + "summary": "Get results of an Arena tournament", + "description": "Players of an Arena tournament, with their score and performance, sorted by rank (best first).\n**Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON)**, i.e. one JSON object per line.\nIf called on an ongoing tournament, results can be inconsistent\ndue to ranking changes while the players are being streamed.\nUse on finished tournaments for guaranteed consistency.\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Max number of players to fetch", + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "in": "query", + "name": "sheet", + "description": "Add a `sheet` field to the player document.\nIt's an expensive server computation that slows down the stream.\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The results of the Arena tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "example": { + "rank": 4, + "score": 389, + "rating": 2618, + "username": "opperwezen", + "title": "IM", + "performance": 2423, + "team": "coders" + } + } + } + } + } + } + } + }, + "/api/tournament/{id}/teams": { + "get": { + "operationId": "teamsByTournament", + "summary": "Get team standing of a team battle", + "description": "Teams of a team battle tournament, with top players, sorted by rank (best first).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of teams of a team battle tournament, with their respective top players.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "example": { + "id": "CdPg1ey4", + "teams": [ + { + "rank": 1, + "id": "cat-lovers", + "score": 842, + "players": [ + { + "user": { + "name": "lizen69", + "id": "lizen69" + }, + "score": 54 + }, + { + "user": { + "name": "lizen249", + "id": "lizen249" + } + } + ] + } + ] + } + } + } + } + } + } + } + }, + "/api/user/{username}/tournament/created": { + "get": { + "operationId": "apiUserNameTournamentCreated", + "summary": "Get tournaments created by a user", + "description": "Get all tournaments created by a given user.\nTournaments are sorted by reverse chronological order of start date (last starting first).\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user whose created tournaments to fetch", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "status", + "description": "Include tournaments in the given status: \"Created\" (10), \"Started\" (20), \"Finished\" (30)\nYou can add this parameter more than once to include tournaments in different statuses.\nExample: `?status=10&status=20`\n", + "schema": { + "type": "integer", + "enum": [ + 10, + 20, + 30 + ] + }, + "required": false + } + ], + "responses": { + "200": { + "description": "The list of tournaments created by the user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + } + } + } + }, + "/api/swiss/new/{teamId}": { + "post": { + "operationId": "apiSwissNew", + "summary": "Create a new Swiss tournament", + "description": "Create a Swiss tournament for your team.\nThis endpoint mirrors the Swiss tournament form from your team pagee.\nYou can create up to 12 tournaments per day.\nAdditional restrictions:\n - clock.limit + clock.increment > 0\n - 15s and 0+1 variant tournaments cannot be rated\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "description": "ID of the team", + "schema": { + "type": "string" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds", + "example": 300, + "enum": [ + 0, + 15, + 30, + 45, + 60, + 90, + 120, + 180, + 240, + 300, + 360, + 420, + 480, + 600, + 900, + 1200, + 1500, + 1800, + 2400, + 3000, + 3600, + 4200, + 4800, + 5400, + 6000, + 6600, + 7200, + 7800, + 8400, + 9000, + 9600, + 10200, + 10800 + ] + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "minimum": 0, + "maximum": 120 + }, + "nbRounds": { + "type": "integer", + "description": "Maximum number of rounds to play", + "minimum": 3, + "maximum": 100 + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds to start the tournament at a given date and time. By default, it starts 10 minutes after creation." + }, + "roundInterval": { + "type": "integer", + "description": "How long to wait between each round, in seconds.\nSet to 99999999 to manually schedule each round from the tournament UI.\nIf empty or -1, a sensible value is picked automatically.\n", + "enum": [ + -1, + 5, + 10, + 20, + 30, + 45, + 60, + 120, + 180, + 300, + 600, + 900, + 1200, + 1800, + 2700, + 3600, + 86400, + 172800, + 604800, + 99999999 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "position": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "password": { + "type": "string", + "description": "Make the tournament private and restrict access with a password." + }, + "forbiddenPairings": { + "type": "string", + "description": "Usernames of players that must not play together.\nTwo usernames per line, separated by a space.\n" + }, + "manualPairings": { + "type": "string", + "description": "Manual pairings for the next round.\nTwo usernames per line, separated by a space. Example:\n```\nPlayerA PlayerB\nPlayerC PlayerD\n```\nTo give a bye (1 point) to a player instead of a pairing, add a line like so:\n```\nPlayerE 1\n```\nMissing players will be considered absent and get zero points.\n" + }, + "chatFor": { + "type": "number", + "description": "Who can read and write in the chat.\n- 0 = No-one\n- 10 = Only team leaders\n- 20 = Only team members\n- 30 = All Lichess players\n", + "default": 20 + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "minimum": 0, + "maximum": 200 + }, + "conditions.playYourGames": { + "type": "boolean", + "description": "Only let players join if they have played their last swiss game.\nIf they failed to show up in a recent swiss event, they won't be able to enter yours.\nThis results in a better swiss experience for the players who actually show up.\n", + "default": false + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clock.limit", + "clock.increment", + "nbRounds" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Swiss tournament was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + }, + "400": { + "description": "The creation of the Swiss tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/swiss/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The Swiss tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "get": { + "operationId": "swiss", + "summary": "Get info about a Swiss tournament", + "description": "Get detailed info about a Swiss tournament.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "responses": { + "200": { + "description": "The information of the Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + } + } + } + }, + "/api/swiss/{id}/edit": { + "post": { + "operationId": "apiSwissUpdate", + "summary": "Update a Swiss tournament", + "description": "Update a Swiss tournament.\nBe mindful not to make important changes to ongoing tournaments.\nAdditional restrictions:\n - clock.limit + clock.increment > 0\n - 15s and 0+1 variant tournaments cannot be rated\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The tournament name. Leave empty to get a random Grandmaster name", + "minLength": 2, + "maxLength": 30 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds", + "example": 300, + "enum": [ + 0, + 15, + 30, + 45, + 60, + 90, + 120, + 180, + 240, + 300, + 360, + 420, + 480, + 600, + 900, + 1200, + 1500, + 1800, + 2400, + 3000, + 3600, + 4200, + 4800, + 5400, + 6000, + 6600, + 7200, + 7800, + 8400, + 9000, + 9600, + 10200, + 10800 + ] + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds", + "example": 1, + "minimum": 0, + "maximum": 120 + }, + "nbRounds": { + "type": "integer", + "description": "Maximum number of rounds to play", + "minimum": 3, + "maximum": 100 + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds to start the tournament at a given date and time. By default, it starts 10 minutes after creation." + }, + "roundInterval": { + "type": "integer", + "description": "How long to wait between each round, in seconds.\nSet to 99999999 to manually schedule each round from the tournament UI, or [with the API](#tag/Swiss-tournaments/operation/apiSwissScheduleNextRound).\nIf empty or -1, a sensible value is picked automatically.\n", + "enum": [ + -1, + 5, + 10, + 20, + 30, + 45, + 60, + 120, + 180, + 300, + 600, + 900, + 1200, + 1800, + 2700, + 3600, + 86400, + 172800, + 604800, + 99999999 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "description": { + "type": "string", + "description": "Anything you want to tell players about the tournament" + }, + "rated": { + "type": "boolean", + "description": "Games are rated and impact players ratings", + "default": true + }, + "password": { + "type": "string", + "description": "Make the tournament private and restrict access with a password." + }, + "forbiddenPairings": { + "type": "string", + "description": "Usernames of players that must not play together.\nTwo usernames per line, separated by a space.\n" + }, + "manualPairings": { + "type": "string", + "description": "Manual pairings for the next round.\nTwo usernames per line, separated by a space.\nPresent players without a valid pairing will be given a bye, which is worth 1 point.\nForfeited players will get 0 points.\n" + }, + "chatFor": { + "type": "number", + "description": "Who can read and write in the chat.\n- 0 = No-one\n- 10 = Only team leaders\n- 20 = Only team members\n- 30 = All Lichess players\n", + "default": 20 + }, + "conditions.minRating.rating": { + "type": "integer", + "description": "Minimum rating to join. Leave empty to let everyone join the tournament.", + "enum": [ + 1000, + 1100, + 1200, + 1300, + 1400, + 1500, + 1600, + 1700, + 1800, + 1900, + 2000, + 2100, + 2200, + 2300, + 2400, + 2500, + 2600 + ] + }, + "conditions.maxRating.rating": { + "type": "integer", + "description": "Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.", + "enum": [ + 2200, + 2100, + 2000, + 1900, + 1800, + 1700, + 1600, + 1500, + 1400, + 1300, + 1200, + 1100, + 1000, + 900, + 800 + ] + }, + "conditions.nbRatedGame.nb": { + "type": "integer", + "description": "Minimum number of rated games required to join.", + "minimum": 0, + "maximum": 200 + }, + "conditions.playYourGames": { + "type": "boolean", + "description": "Only let players join if they have played their last swiss game.\nIf they failed to show up in a recent swiss event, they won't be able to enter yours.\nThis results in a better swiss experience for the players who actually show up.\n", + "default": false + }, + "conditions.allowList": { + "type": "string", + "description": "Predefined list of usernames that are allowed to join, separated by commas.\nIf this list is non-empty, then usernames absent from this list will be forbidden to join.\nAdding `%titled` to the list additionally allows any titled player to join.\nExample: `thibault,german11,%titled`\n" + } + }, + "required": [ + "clock.limit", + "clock.increment", + "nbRounds" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The Swiss tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + }, + "400": { + "description": "Updating the swiss failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "This user cannot update this Swiss.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissUnauthorisedEdit" + } + } + } + } + } + } + }, + "/api/swiss/{id}/schedule-next-round": { + "post": { + "operationId": "apiSwissScheduleNextRound", + "summary": "Manually schedule the next round", + "description": "Manually schedule the next round date and time of a Swiss tournament.\nThis sets the `roundInterval` field to `99999999`, i.e. manual scheduling.\nAll further rounds will need to be manually scheduled, unless the `roundInterval` field is changed back to automatic scheduling.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the tournament", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "date": { + "type": "integer", + "description": "Timestamp in milliseconds to start the next round at a given date and time." + } + } + } + } + } + }, + "responses": { + "204": { + "description": "The Swiss tournament was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + }, + "400": { + "description": "Updating the swiss failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "This user cannot update this Swiss.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SwissUnauthorisedEdit" + } + } + } + } + } + } + }, + "/api/swiss/{id}/join": { + "post": { + "operationId": "apiSwissJoin", + "summary": "Join a Swiss tournament", + "description": "Join a Swiss tournament, possibly with a password.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "requestBody": { + "description": "You may need these depending on the tournament to join", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "password": { + "type": "string", + "description": "The tournament password, if one is required" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The tournament was successfully joined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Joining the tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/swiss/{id}/withdraw": { + "post": { + "operationId": "apiSwissWithdraw", + "summary": "Pause or leave a swiss tournament", + "description": "Leave a future Swiss tournament, or take a break on an ongoing Swiss tournament.\nIt's possible to join again later. Points are preserved.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string", + "example": "hL7vMrFQ" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tournament was successfully paused or left.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/swiss/{id}/terminate": { + "post": { + "operationId": "apiSwissTerminate", + "summary": "Terminate a Swiss tournament", + "description": "Terminate a Swiss tournament\n", + "tags": [ + "Swiss tournaments" + ], + "security": [ + { + "OAuth2": [ + "tournament:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The Swiss tournament ID.", + "schema": { + "type": "string", + "example": "W5FrxusN" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The Swiss tournament was successfully terminated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Terminating the Swiss tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/swiss/{id}.trf": { + "get": { + "operationId": "swissTrf", + "summary": "Export TRF of a Swiss tournament", + "description": "Download a tournament in the Tournament Report File format, the FIDE standard.\nDocumentation: <https://www.fide.com/FIDE/handbook/C04Annex2_TRF16.pdf>\nExample: <https://lichess.org/swiss/j8rtJ5GL.trf>\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The TRF representation of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/api/swiss/{id}/games": { + "get": { + "operationId": "gamesBySwiss", + "summary": "Export games of a Swiss tournament", + "description": "Download games of a swiss tournament in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format.\nGames are sorted by reverse chronological order (last round first).\nThe game stream is throttled, depending on who is making the request:\n - Anonymous request: 20 games per second\n - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "player", + "description": "Only the games played by a given player", + "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.\nEither as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\nOr in a `clocks` JSON field, as centisecond integers, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "evals", + "description": "Include analysis evaluations and comments, when available.\nEither as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }`\nOr in an `analysis` JSON field, depending on the response type.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "accuracy", + "description": "Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available.\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "opening", + "description": "Include the opening name.\nExample: `[Opening \"King's Gambit Accepted, King's Knight Gambit\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "division", + "description": "Plies which mark the beginning of the middlegame and endgame.\nOnly available in JSON\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of games of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/GamePgn" + } + }, + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + } + } + } + }, + "/api/swiss/{id}/results": { + "get": { + "operationId": "resultsBySwiss", + "summary": "Get results of a swiss tournament", + "description": "Players of a swiss tournament, with their score and performance, sorted by rank (best first).\nPlayers are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nIf called on an ongoing tournament, results can be inconsistent\ndue to ranking changes while the players are being streamed.\nUse on finished tournaments for guaranteed consistency.\n", + "tags": [ + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "id", + "description": "The tournament ID.", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "nb", + "description": "Max number of players to fetch", + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The results of a Swiss tournament.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "example": { + "rank": 4, + "points": 8.5, + "tieBreak": 77, + "rating": 2618, + "username": "opperwezen", + "title": "IM", + "performance": 2423 + } + } + } + } + } + } + } + }, + "/api/team/{teamId}/swiss": { + "get": { + "operationId": "apiTeamSwiss", + "summary": "Get team swiss tournaments", + "description": "Get all swiss tournaments of a team.\nTournaments are sorted by reverse chronological order of start date (last starting first).\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Teams", + "Swiss tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true, + "example": "coders" + }, + { + "in": "query", + "name": "max", + "description": "How many tournaments to download.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "The list of Swiss tournaments of a team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/nd-json": { + "schema": { + "$ref": "#/components/schemas/SwissTournament" + } + } + } + } + } + } + }, + "/api/study/{studyId}/{chapterId}.pgn": { + "get": { + "operationId": "studyChapterPgn", + "summary": "Export one study chapter", + "description": "Download one study chapter in PGN format.\n", + "tags": [ + "Studies" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "chapterId", + "description": "The chapter ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The chapter of the study.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/study/{studyId}.pgn": { + "get": { + "operationId": "studyAllChaptersPgn", + "summary": "Export all chapters", + "description": "Download all chapters of a study in PGN format.\n", + "tags": [ + "Studies" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the study.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + }, + "Last-Modified": { + "schema": { + "type": "string", + "example": "Tue, 25 Apr 2023 13:23:09 GMT" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + }, + "head": { + "operationId": "studyAllChaptersHead", + "summary": "Study metadata", + "description": "Only get the study headers, including `Last-Modified`.\n", + "tags": [ + "Studies" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The study headers.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + }, + "Last-Modified": { + "schema": { + "type": "string", + "example": "Tue, 25 Apr 2023 13:23:09 GMT" + } + } + } + } + } + } + }, + "/api/study/{studyId}/import-pgn": { + "post": { + "operationId": "apiStudyImportPGN", + "summary": "Import PGN into a study", + "description": "Imports arbitrary PGN into an existing [study](https://lichess.org/study). Creates a new chapter in the study.\nIf the PGN contains multiple games (separated by 2 or more newlines)\nthen multiple chapters will be created within the study.\nNote that a study can contain at most 64 chapters.\n", + "tags": [ + "Studies" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "ID of the study", + "schema": { + "type": "string" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the import", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the new chapter.\nIf multiple chapters are created, the names will be infered from the PGN tags.\n", + "minLength": 1, + "maxLength": 100 + }, + "pgn": { + "type": "string", + "description": "PGN to import. Can contain multiple games separated by 2 or more newlines.\n" + }, + "orientation": { + "type": "string", + "description": "Default board orientation.", + "enum": [ + "white", + "black" + ], + "default": "white" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + } + }, + "required": [ + "name", + "pgn" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The chapters that were created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StudyImportPgnChapters" + } + } + } + }, + "400": { + "description": "The creation of the chapter(s) failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study/by/{username}/export.pgn": { + "get": { + "operationId": "studyExportAllPgn", + "summary": "Export all studies of a user", + "description": "Download all chapters of all studies of a user in PGN format.\nIf authenticated, then all public, unlisted, and private studies are included.\nIf not, only public (non-unlisted) studies are included.\n", + "tags": [ + "Studies" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user whose studies we export", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "clocks", + "description": "Include clock comments in the PGN moves, when available.\nExample: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "comments", + "description": "Include analysis and annotator comments in the PGN moves, when available.\nExample: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "variations", + "description": "Include non-mainline moves, when available.\nExample: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2`\n", + "schema": { + "type": "boolean", + "default": true + } + }, + { + "in": "query", + "name": "source", + "description": "Add a `Source` PGN tag with the study chapter URL.\nExample: `[Source \"https://lichess.org/study/4NBHImfM/1Tk4IyTz\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "orientation", + "description": "Add a `Orientation` PGN tag with the chapter predefined orientation.\nExample: `[Orientation \"white\"]`\n", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The studies of the user.", + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/study/by/{username}": { + "get": { + "operationId": "studyListMetadata", + "summary": "List studies of a user", + "description": "Get metadata (name and dates) of all studies of a user.\nIf authenticated, then all public, unlisted, and private studies are included.\nIf not, only public (non-unlisted) studies are included.\nStudies are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Studies" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "description": "The user whose studies we list", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of studies.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StudyMetadata" + } + } + } + } + } + } + } + }, + "/api/study/{studyId}/{chapterId}": { + "delete": { + "operationId": "apiStudyStudyIdChapterIdDelete", + "summary": "Delete a study chapter", + "tags": [ + "Studies" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "studyId", + "description": "The study ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "chapterId", + "description": "The chapter ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "description": "Delete a chapter of a study you own. This is definitive.\nA study must have at least one chapter; so if you delete the last chapter,\nan empty one will be automatically created to replace it.\n", + "responses": { + "204": { + "description": "Chapter successfully deleted", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/api/broadcast": { + "get": { + "operationId": "broadcastIndex", + "summary": "Get official broadcasts", + "description": "Get all incoming, ongoing, and finished official broadcasts.\nThe broadcasts are sorted by start date, most recent first.\nBroadcasts are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "Max number of broadcasts to fetch", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "The list of official broadcasts.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + } + } + } + } + }, + "/broadcast/new": { + "post": { + "operationId": "broadcastTourCreate", + "summary": "Create a broadcast tournament", + "description": "Create a new broadcast tournament to relay external games.\nThis endpoint accepts the same form data as the [web form](https://lichess.org/broadcast/new).\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/BroadcastForm" + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast tournament was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + }, + "400": { + "description": "The creation of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/broadcast/{broadcastTournamentId}": { + "get": { + "operationId": "broadcastTourGet", + "summary": "Get a broadcast tournament", + "description": "Get information about a broadcast tournament.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The information about the broadcast tournament.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastTour" + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentId}/leaderboard": { + "get": { + "operationId": "broadcastLeaderboardGet", + "summary": "Get a broadcast leaderboard", + "description": "Get the leaderboard of a broadcast tournament, if available.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The broadcast leaderboard players", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BroadcastLeaderboardEntry" + } + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentId}/edit": { + "post": { + "operationId": "broadcastTourUpdate", + "summary": "Update your broadcast tournament", + "description": "Update information about a broadcast tournament that you created.\nThis endpoint accepts the same form data as the web form.\nAll fields must be populated with data. Missing fields will override the broadcast with empty data.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/BroadcastForm" + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast tournament was successfully edited.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The edition of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/{broadcastTournamentId}/new": { + "post": { + "operationId": "broadcastRoundCreate", + "summary": "Create a broadcast round", + "description": "Create a new broadcast round to relay external games.\nThis endpoint accepts the same form data as the web form.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast round. Length must be between 3 and 80 characters.\nExample: `Round 1`\n" + }, + "syncUrl": { + "type": "string", + "description": "URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet.\nExample: `https://myserver.org/myevent/round-10/games.pgn`\nIf the syncUrl is missing, then the broadcast needs to be fed by [pushing PGN to it](#operation/broadcastPush).\n" + }, + "syncUrlRound": { + "type": "string", + "description": "Required if `syncUrl` contains a livechesscloud link.\n" + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds of broadcast round start. Leave empty to manually start the broadcast round.\nExample: `1356998400070`\n", + "minimum": 1356998400070 + }, + "delay": { + "type": "integer", + "description": "Delay in seconds for movements to appear on the broadcast. Leave it empty if you don't need it.\nExample: `900` (15 min)\n", + "minimum": 0, + "maximum": 1800 + }, + "period": { + "type": "integer", + "description": "(Only for Admins) Waiting time for each poll.\n", + "minimum": 2, + "maximum": 60 + }, + "finished": { + "type": "boolean", + "description": "Mark whether the round has been completed.\n", + "default": false + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast round was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastRound" + } + } + } + }, + "400": { + "description": "The creation of the broadcast failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/broadcast/{broadcastTournamentSlug}/{broadcastRoundSlug}/{broadcastRoundId}": { + "get": { + "operationId": "broadcastRoundGet", + "summary": "Get a broadcast round", + "description": "Get information about a broadcast round.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentSlug", + "description": "The broadcast tournament slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastRoundId` is actually used.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "broadcastRoundSlug", + "description": "The broadcast round slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastRoundId` is actually used.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast Round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The information about the broadcast round.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastRound" + } + } + } + } + } + } + }, + "/broadcast/round/{broadcastRoundId}/edit": { + "post": { + "operationId": "broadcastRoundUpdate", + "summary": "Update your broadcast round", + "description": "Update information about a broadcast round that you created.\nThis endpoint accepts the same form data as the web form.\nAll fields must be populated with data. Missing fields will override the broadcast with empty data.\nFor instance, if you omit `startDate`, then any pre-existing start date will be removed.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast round. Length must be between 3 and 80 characters.\nExample: `Round 10`\n" + }, + "syncUrl": { + "type": "string", + "description": "URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet.\nExample: `https://myserver.org/myevent/round-10/games.pgn`\n" + }, + "syncUrlRound": { + "type": "string", + "description": "Required if `syncUrl` contains a livechesscloud link.\n" + }, + "startsAt": { + "type": "integer", + "description": "Timestamp in milliseconds of broadcast start. Leave empty to manually start the broadcast.\nExample: `1356998400070`\n", + "minimum": 1356998400070 + }, + "delay": { + "type": "integer", + "description": "Delay in seconds for movements to appear on the broadcast. Leave it empty if you don't need it.\nExample: `900` (15 min)\n", + "minimum": 0, + "maximum": 1800 + }, + "period": { + "type": "integer", + "description": "(Only for Admins) Waiting time for each poll.\n", + "minimum": 2, + "maximum": 60 + }, + "finished": { + "type": "boolean", + "description": "Mark whether the round has been completed.\n", + "default": false + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast round was successfully edited.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The edition of the broadcast tournament failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/broadcast/round/{broadcastRoundId}/push": { + "post": { + "operationId": "broadcastPush", + "summary": "Push PGN to your broadcast round", + "description": "Update your broadcast with new PGN.\nOnly for broadcast without a source URL.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The PGN. It can contain up to 64 games, separated by a double new line.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "examples": { + "broadcastPgnPushRequest": { + "$ref": "#/components/examples/broadcastPgnPushRequest" + } + } + } + } + }, + "responses": { + "200": { + "description": "The broadcast was successfully updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastPgnPush" + }, + "examples": { + "broadcastPgnPushResponse": { + "$ref": "#/components/examples/broadcastPgnPushResponse" + } + } + } + } + }, + "400": { + "description": "There was a problem with the pushed PGN.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "properties": { + "error": { + "type": "string" + } + }, + "example": { + "error": "Cannot parse moves" + } + } + } + } + } + } + } + }, + "/api/stream/broadcast/round/{broadcastRoundId}.pgn": { + "get": { + "operationId": "broadcastStreamRoundPgn", + "summary": "Stream an ongoing broadcast tournament as PGN", + "description": "This streaming endpoint first sends all games of a broadcast tournament in PGN format.\nThen, it waits for new moves to be played. As soon as it happens, the entire PGN of the game is sent to the stream.\nThe stream will also send PGNs when games are added to the tournament.\nThis is the best way to get updates about an ongoing tournament. Streaming means no polling,\nand no pollings means no latency, and minimum impact on the server.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The broadcast round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the tournament games, then the PGNs of games as they are updated.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast/round/{broadcastRoundId}.pgn": { + "get": { + "operationId": "broadcastRoundPgn", + "summary": "Export one round as PGN", + "description": "Download all games of a single round of a broadcast tournament in PGN format.\nYou *could* poll this endpoint to get updates about a tournament, but it would be slow,\nand very inefficient.\nInstead, consider [streaming the tournament](#operation/broadcastStreamRoundPgn) to get\na new PGN every time a game is updated, in real-time.\n", + "tags": [ + "Broadcasts" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "broadcastRoundId", + "description": "The round ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the round.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast/{broadcastTournamentId}.pgn": { + "get": { + "operationId": "broadcastAllRoundsPgn", + "summary": "Export all rounds as PGN", + "description": "Download all games of all rounds of a broadcast in PGN format.\nIf a `study:read` [OAuth token](#tag/OAuth) is provided,\nthe private rounds where the user is a contributor will be available.\nYou may want to [download only the games of a single round](#operation/broadcastRoundPgn) instead.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "broadcastTournamentId", + "description": "The broadcast tournament ID (8 characters).", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The PGN representation of the broadcast.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/StudyPgn" + } + } + } + } + } + } + }, + "/api/broadcast/my-rounds": { + "get": { + "operationId": "broadcastMyRoundsGet", + "summary": "Get your broadcast rounds", + "description": "Stream all broadcast rounds you are a member of.\nAlso includes broadcasts rounds you did not create, but were invited to.\nAlso includes broadcasts rounds where you're a non-writing member. See the `writeable` flag in the response.\nRounds are ordered by rank, which is roughly chronological, most recent first, slightly pondered with popularity.\n", + "tags": [ + "Broadcasts" + ], + "security": [ + { + "OAuth2": [ + "study:read" + ] + } + ], + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "How many rounds to get", + "schema": { + "type": "integer", + "minimum": 1, + "example": 20 + } + } + ], + "responses": { + "200": { + "description": "The broadcast rounds with their tournament and a `study.writeable` flag.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BroadcastMyRound" + } + } + } + } + } + } + }, + "/api/simul": { + "get": { + "operationId": "apiSimul", + "summary": "Get current simuls", + "description": "Get recently created, started, finished, simuls.\nCreated and finished simul lists are not exhaustives, only those with\nstrong enough host will be listed, the same filter is used to display simuls on https://lichess.org/simul.\nWhen [authenticated with OAuth2](#section/Introduction/Authentication), the pending list will be populated with your created, but unstarted simuls.\n", + "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" + } + } + } + } + } + } + } + } + } + }, + "/api/team/{teamId}": { + "get": { + "operationId": "teamShow", + "summary": "Get a single team", + "description": "Public info about a team. Includes the list of publicly visible leaders.", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The information about the team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Team" + } + } + } + } + } + } + }, + "/api/team/all": { + "get": { + "operationId": "teamAll", + "summary": "Get popular teams", + "description": "Paginator of the most popular teams.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "page", + "schema": { + "type": "number", + "example": 1, + "default": 1 + } + } + ], + "responses": { + "200": { + "description": "A paginated list of the most popular teams.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TeamPaginatorJson" + } + } + } + } + } + } + }, + "/api/team/of/{username}": { + "get": { + "operationId": "teamOfUsername", + "summary": "Teams of a player", + "description": "All the teams a player is a member of.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of teams the user is a member of.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Team" + } + } + } + } + } + } + } + }, + "/api/team/search": { + "get": { + "operationId": "teamSearch", + "summary": "Search teams", + "description": "Paginator of team search results for a keyword.\n", + "tags": [ + "Teams" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "text", + "schema": { + "type": "string", + "example": "coders" + } + }, + { + "in": "query", + "name": "page", + "schema": { + "type": "number", + "example": 1, + "default": 1 + } + } + ], + "responses": { + "200": { + "description": "The paginated list of teams.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TeamPaginatorJson" + } + } + } + } + } + } + }, + "/api/team/{teamId}/users": { + "get": { + "operationId": "teamIdUsers", + "summary": "Get members of a team", + "description": "Members are sorted by reverse chronological order of joining the team (most recent first).\nOAuth is only required if the list of members is private.\nMembers are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of users in the team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/team/{teamId}/arena": { + "get": { + "operationId": "apiTeamArena", + "summary": "Get team Arena tournaments", + "description": "Get all Arena tournaments relevant to a team.\nTournaments are sorted by reverse chronological order of start date (last starting first).\nTournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Teams", + "Arena tournaments" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "teamId", + "description": "ID of the team", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "max", + "description": "How many tournaments to download.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "The list of Arena tournaments of a team.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + } + } + } + }, + "/team/{teamId}/join": { + "post": { + "operationId": "teamIdJoin", + "summary": "Join a team", + "description": "Join a team.\nIf the team requires a password but the `password` field is incorrect,\nthen the call fails with `403 Forbidden`.\nSimilarly, if the team join policy requires a confirmation but the\n`message` parameter is not given, then the call fails with\n`403 Forbidden`.\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Optional request message, if the team requires one." + }, + "password": { + "type": "string", + "description": "Optional password, if the team requires one." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The request to join a team was successfully sent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/team/{teamId}/quit": { + "post": { + "operationId": "teamIdQuit", + "summary": "Leave a team", + "description": "Leave a team.\n- <https://lichess.org/team>\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The logged in user has successfully left the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/team/{teamId}/requests": { + "get": { + "operationId": "teamRequests", + "summary": "Get join requests", + "description": "Get pending join requests of your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:read" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "declined", + "description": "Get the declined join requests", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "The list of pending join requests on your team", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TeamRequestWithUser" + }, + "example": [ + { + "request": { + "date": 1644232474472, + "message": "Hello, I would like to join the team!", + "teamId": "coders", + "userId": "neio" + }, + "user": { + "createdAt": 1338509698620, + "id": "neio", + "perfs": { + "blitz": { + "games": 70, + "prog": 81, + "prov": true, + "rating": 1729, + "rd": 124 + }, + "chess960": { + "games": 2, + "prog": 0, + "prov": true, + "rating": 1528, + "rd": 266 + } + }, + "playTime": { + "total": 152902, + "tv": 20800 + }, + "profile": { + "bio": "yuwnt uyn", + "country": "AL", + "firstName": "wyutn w[fuyt", + "lastName": "ywut wyufth" + }, + "seenAt": 1644232201429, + "title": "NM", + "username": "Neio" + } + } + ] + } + } + } + } + } + } + }, + "/api/team/{teamId}/request/{userId}/accept": { + "post": { + "operationId": "teamRequestAccept", + "summary": "Accept join request", + "description": "Accept someone's request to join your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The member has been added to the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/team/{teamId}/request/{userId}/decline": { + "post": { + "operationId": "teamRequestDecline", + "summary": "Decline join request", + "description": "Decline someone's request to join your team", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The join request has been declined and is no longer pending.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/team/{teamId}/kick/{userId}": { + "post": { + "operationId": "teamIdKickUserId", + "summary": "Kick a user from your team", + "description": "Kick a member out of one of your teams.\n- <https://lichess.org/team>\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + }, + { + "in": "path", + "name": "userId", + "schema": { + "type": "string", + "example": "neio" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The member has been kicked from the team.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/team/{teamId}/pm-all": { + "post": { + "operationId": "teamIdPmAll", + "summary": "Message all members", + "description": "Send a private message to all members of a team.\nYou must be a team leader with the \"Messages\" permission.\n", + "tags": [ + "Teams" + ], + "security": [ + { + "OAuth2": [ + "team:lead" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "teamId", + "schema": { + "type": "string", + "example": "coders" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "The message to send to all your team members." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The message has successfully been sent to all team members.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The sending of message to all team members has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/streamer/live": { + "get": { + "operationId": "streamerLive", + "summary": "Get live streamers", + "description": "Get basic info about currently streaming users.\nThis API is very fast and cheap on lichess side.\nSo you can call it quite often (like once every 5 seconds).\n", + "tags": [ + "Users" + ], + "security": [], + "responses": { + "200": { + "description": "The list of live streamers and their respective information.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUser" + }, + "example": [ + { + "id": "chess-network", + "name": "Chess-Network", + "title": "NM", + "patron": true, + "stream": { + "service": "twitch", + "status": "Tuesday night 🐴 chess | lichess.org", + "lang": "en" + }, + "streamer": { + "name": "ChessNetwork", + "headline": "Chess with commentary, tournament competition, viewer interaction, and more.", + "description": "I'm a self-taught National Master in chess from Pennsylvania, USA who was introduced to the game by my father in 1988 at age 8. I've been playing since, enjoy teaching, and have been a broadcaster of all things chess since 2011. It's my hope your experience with this stream is both fun and educational. 😎 -Jerry", + "twitch": "https://twitch.tv/chessnetwork", + "youTube": "https://www.youtube.com/channel/UCCDOQrpqLqKVcTCKzqarxLg/live", + "image": "https://image.lichess1.org/display?h=350&op=thumbnail&path=orlandikill:streamer:orlandikill:wiw356Np.jpg&w=350&sig=9912e0c45e42f37e7cd2716af6bd41bb10497b0c" + } + } + ] + } + } + } + } + } + } + }, + "/api/crosstable/{user1}/{user2}": { + "get": { + "operationId": "apiCrosstable", + "summary": "Get crosstable", + "description": "Get total number of games, and current score, of any two users.\nIf the `matchup` flag is provided, and the users are currently playing, also gets the current match game number and scores.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "user1", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "path", + "name": "user2", + "schema": { + "type": "string" + }, + "required": true + }, + { + "in": "query", + "name": "matchup", + "description": "Whether to get the current match data, if any", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The crosstable of the two users.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Crosstable" + } + } + } + } + } + } + }, + "/api/player/autocomplete": { + "get": { + "operationId": "apiPlayerAutocomplete", + "summary": "Autocomplete usernames", + "description": "Provides autocompletion options for an incomplete username.\n", + "tags": [ + "Users" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "term", + "description": "The beginning of a username", + "schema": { + "type": "string", + "minLength": 3 + }, + "required": true + }, + { + "in": "query", + "name": "object", + "description": "- `false` returns an array of usernames\n- `true` returns an object with matching users\n", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "in": "query", + "name": "friend", + "description": "Returns followed players matching `term` if any, else returns other players.\nRequires [OAuth](#tag/OAuth).\n", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "An array of players which usernames start with the provided term.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUserOnline" + } + } + } + } + ] + } + } + } + } + } + } + }, + "/api/user/{username}/note": { + "post": { + "operationId": "writeNote", + "summary": "Add a note for a user", + "description": "Add a private note available only to you about this account.\n", + "tags": [ + "Users" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "text": { + "description": "The contents of the note", + "type": "string" + } + }, + "required": [ + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The note was successfully added.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + }, + "get": { + "operationId": "readNote", + "summary": "Get notes for a user", + "description": "Get the private notes that you have added for a user.\n", + "tags": [ + "Users" + ], + "security": [ + { + "OAuth2": [] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The list of notes you have added for this user", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserNote" + }, + "example": [ + { + "from": { + "name": "thibault", + "patron": true, + "id": "thibault" + }, + "to": { + "name": "DrNykterstein", + "title": "GM", + "patron": true, + "id": "drnykterstein" + }, + "text": "This guy is good at chess", + "date": 1690585691898 + } + ] + } + } + } + } + } + } + }, + "/api/rel/following": { + "get": { + "operationId": "apiUserFollowing", + "summary": "Get users followed by the logged in user", + "description": "Users are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:read" + ] + } + ], + "responses": { + "200": { + "description": "The list of users followed by a user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/UserExtended" + } + } + } + } + } + } + }, + "/api/rel/follow/{username}": { + "post": { + "operationId": "followUser", + "summary": "Follow a player", + "description": "Follow a player, adding them to your list of Lichess friends.\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player was successfully added.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/rel/unfollow/{username}": { + "post": { + "operationId": "unfollowUser", + "summary": "Unfollow a player", + "description": "Unfollow a player, removing them from your list of Lichess friends.\n", + "tags": [ + "Relations" + ], + "security": [ + { + "OAuth2": [ + "follow:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "thibault" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player was successfully removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/stream/event": { + "get": { + "operationId": "apiStreamEvent", + "summary": "Stream incoming events", + "description": "\n Stream the events reaching a lichess user in real time as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\n An empty line is sent every 6 seconds for keep alive purposes.\n\n Each non-empty line is a JSON object containing a `type` field. Possible values are:\n - `gameStart` Start of a game\n - `gameFinish` Completion of a game\n - `challenge` A player sends you a challenge or you challenge someone\n - `challengeCanceled` A player cancels their challenge to you\n - `challengeDeclined` The opponent declines your challenge\n \n When the stream opens, all current challenges and games are sent.", + "tags": [ + "Board", + "Bot" + ], + "security": [ + { + "OAuth2": [ + "challenge:read", + "bot:play", + "board:play" + ] + } + ], + "responses": { + "200": { + "description": "The stream of events reaching the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameStartEvent" + }, + { + "$ref": "#/components/schemas/GameFinishEvent" + }, + { + "$ref": "#/components/schemas/ChallengeEvent" + }, + { + "$ref": "#/components/schemas/ChallengeCanceledEvent" + }, + { + "$ref": "#/components/schemas/ChallengeDeclinedEvent" + } + ] + } + } + } + } + } + } + }, + "/api/board/seek": { + "post": { + "operationId": "apiBoardSeek", + "summary": "Create a seek", + "description": "\n Create a public seek, to start a game with a random player.\n\n ### Real-time seek\n\n Specify the `time` and `increment` clock values. The response is streamed but doesn't contain any information.\n\n **Keep the connection open to keep the seek active**.\n\n If the client closes the connection, the seek is canceled. This way, if the client terminates, the user won't be paired in a game they wouldn't play.\n When the seek is accepted, or expires, the server closes the connection.\n\n **Make sure to also have an [Event stream](#operation/apiStreamEvent) open**, to be notified when a game starts.\n We recommend opening the [Event stream](#operation/apiStreamEvent) first, then the seek stream. This way,\n you won't miss the game event if the seek is accepted immediately.\n\n ### Correspondence seek\n\n Specify the `days` per turn value. The response is not streamed, it immediately completes with the seek ID. The seek remains active on the server until it is joined by someone.", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "requestBody": { + "description": "Parameters of the seek", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Whether the game is rated and impacts players ratings.", + "example": true, + "default": false + }, + "time": { + "type": "number", + "description": "Clock initial time in minutes. Required for real-time seeks.", + "example": 15, + "minimum": 0, + "maximum": 180 + }, + "increment": { + "type": "integer", + "description": "Clock increment in seconds. Required for real-time seeks.", + "example": 15, + "minimum": 0, + "maximum": 180 + }, + "days": { + "type": "integer", + "description": "Days per turn. Required for correspondence seeks.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "color": { + "type": "string", + "description": "The color to play. Better left empty to automatically get 50% white.", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "ratingRange": { + "type": "string", + "description": "The rating range of potential opponents. Better left empty.\nExample: 1500-1800\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The seek was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "text/plain": { + "example": "" + } + } + }, + "400": { + "description": "The creation of the seek failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/stream/{gameId}": { + "get": { + "operationId": "boardGameStream", + "summary": "Stream Board game state", + "description": " Stream the state of a game being played with the Board API, as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nUse this endpoint to get updates about the game in real-time, with a single request.\n\nEach line is a JSON object containing a `type` field. Possible values are:\n - `gameFull` Full game data. All values are immutable, except for the `state` field.\n - `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.\n - `chatLine` Chat message sent by a user in the `room` \"player\" or \"spectator\".\n\n - `opponentGone` Whether the opponent has left the game, and how long before you can claim a win or draw.\n\n \nThe first line is always of type `gameFull`.\n\n \nThe server closes the stream when the game ends, or if the game has already ended.", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameFullEvent" + }, + { + "$ref": "#/components/schemas/GameStateEvent" + }, + { + "$ref": "#/components/schemas/ChatLineEvent" + }, + { + "$ref": "#/components/schemas/OpponentGone" + } + ] + } + } + } + }, + "404": { + "description": "The game was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/move/{move}": { + "post": { + "operationId": "boardGameMove", + "summary": "Make a Board move", + "description": "Make a move in a game being played with the Board API.\nThe move can also contain a draw offer/agreement.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "move", + "required": true, + "description": "The move to play, in UCI format", + "schema": { + "type": "string", + "example": "e2e4" + } + }, + { + "in": "query", + "name": "offeringDraw", + "description": "Whether to offer (or agree to) a draw", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The move was successfully made.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The move failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/chat": { + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "post": { + "operationId": "boardGameChatPost", + "summary": "Write in the chat", + "description": "Post a message to the player or spectator chat, in a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "room", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The message was successfully posted in the chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The posting of the message in the chat failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "get": { + "operationId": "boardGameChatGet", + "summary": "Fetch the game chat", + "description": "Get the messages posted in the game chat\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "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/GameChat" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/abort": { + "post": { + "operationId": "boardGameAbort", + "summary": "Abort a game", + "description": "Abort a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game successfully aborted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The abortion of the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/resign": { + "post": { + "operationId": "boardGameResign", + "summary": "Resign a game", + "description": "Resign a game being played with the Board API.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully resigned.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The resigning from the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/draw/{accept}": { + "post": { + "operationId": "boardGameDraw", + "summary": "Handle draw offers", + "description": "Create/accept/decline draw offers.\n- `yes`: Offer a draw, or accept the opponent's draw offer.\n- `no`: Decline a draw offer from the opponent.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The draw offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The draw offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/takeback/{accept}": { + "post": { + "operationId": "boardGameTakeback", + "summary": "Handle takeback offers", + "description": "Create/accept/decline takebacks.\n- `yes`: Propose a takeback, or accept the opponent's takeback offer.\n- `no`: Decline a takeback offer from the opponent.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The takeback offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The takeback offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/claim-victory": { + "post": { + "operationId": "boardGameClaimVictory", + "summary": "Claim victory of a game", + "description": "Claim victory when the opponent has left the game for a while.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The victory was successfully claimed.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The victory claim has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/board/game/{gameId}/berserk": { + "post": { + "operationId": "boardGameBerserk", + "summary": "Berserk a tournament game", + "description": "Go berserk on an arena tournament game. Halves the clock time, grants an extra point upon winning.\nOnly available in arena tournaments that allow berserk, and before each player has made a move.\n", + "tags": [ + "Board" + ], + "security": [ + { + "OAuth2": [ + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The player successfully whent berserk.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The berserk has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/online": { + "get": { + "operationId": "apiBotOnline", + "summary": "Get online bots", + "tags": [ + "Bot" + ], + "security": [], + "description": "Stream the [online bot users](https://lichess.org/player/bots), as [ndjson](#section/Introduction/Streaming-with-ND-JSON). Throttled to 50 bot users per second.", + "parameters": [ + { + "in": "query", + "name": "nb", + "description": "How many bot users to fetch", + "schema": { + "type": "integer", + "minimum": 1, + "example": 20 + } + } + ], + "responses": { + "200": { + "description": "The list of online bot users", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/User" + }, + "example": { + "id": "georges-bot", + "username": "Georges-bot", + "perfs": { + "chess960": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "atomic": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "racingKings": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "ultraBullet": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "blitz": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "kingOfTheHill": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "bullet": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "correspondence": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "horde": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "puzzle": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "classical": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "rapid": { + "games": 2945, + "rating": 1609, + "rd": 60, + "prog": -22, + "prov": true + }, + "storm": { + "runs": 44, + "score": 61 + }, + "racer": { + "runs": 44, + "score": 61 + }, + "streak": { + "runs": 44, + "score": 61 + } + }, + "createdAt": 1290415680000, + "disabled": false, + "tosViolation": false, + "profile": { + "country": "EC", + "location": "string", + "bio": "Free bugs!", + "firstName": "Thibault", + "lastName": "Duplessis", + "fideRating": 1500, + "uscfRating": 1500, + "ecfRating": 1500, + "cfcRating": 1500, + "dsbRating": 1500, + "links": "github.com/ornicar\r\ntwitter.com/ornicar" + }, + "seenAt": 1522636452014, + "patron": true, + "verified": true, + "playTime": { + "total": 3296897, + "tv": 12134 + }, + "title": "BOT" + } + } + } + } + } + } + }, + "/api/bot/account/upgrade": { + "post": { + "operationId": "botAccountUpgrade", + "summary": "Upgrade to Bot account", + "description": "Upgrade a lichess player account into a Bot account. Only Bot accounts can use the Bot API.\nThe 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.\nTo upgrade an account to Bot, use the [official lichess-bot client](https://github.com/lichess-bot-devs/lichess-bot), or follow these steps:\n- Create an [API access token](https://lichess.org/account/oauth/token/create?scopes[]=bot:play) with \"Play bot moves\" permission.\n- `curl -d '' https://lichess.org/api/bot/account/upgrade -H \"Authorization: Bearer <yourTokenHere>\"`\nTo know if an account has already been upgraded, use the [Get my profile API](#operation/accountMe):\nthe `title` field should be set to `BOT`.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "responses": { + "200": { + "description": "The bot account was successfully upgraded.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The upgrade of the bot account failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/stream/{gameId}": { + "get": { + "operationId": "botGameStream", + "summary": "Stream Bot game state", + "description": " Stream the state of a game being played with the Bot API, as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\n\nUse this endpoint to get updates about the game in real-time, with a single request.\n\nEach line is a JSON object containing a `type` field. Possible values are:\n - `gameFull` Full game data. All values are immutable, except for the `state` field.\n - `gameState` Current state of the game. Immutable values not included.\n - `chatLine` Chat message sent by a user (or the bot itself) in the `room` \"player\" or \"spectator\".\n\n - `opponentGone` Whether the opponent has left the game, and how long before you can claim a win or draw.\n\n \nThe first line is always of type `gameFull`.", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The stream of the bot game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/GameFullEvent" + }, + { + "$ref": "#/components/schemas/GameStateEvent" + }, + { + "$ref": "#/components/schemas/ChatLineEvent" + }, + { + "$ref": "#/components/schemas/OpponentGone" + } + ] + } + } + } + }, + "404": { + "description": "The bot game was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/move/{move}": { + "post": { + "operationId": "botGameMove", + "summary": "Make a Bot move", + "description": "Make a move in a game being played with the Bot API.\nThe move can also contain a draw offer/agreement.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "move", + "required": true, + "description": "The move to play, in UCI format", + "schema": { + "type": "string", + "example": "e2e4" + } + }, + { + "in": "query", + "name": "offeringDraw", + "description": "Whether to offer (or agree to) a draw", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "The bot move was successfully made.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The bot move failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/chat": { + "post": { + "operationId": "botGameChat", + "summary": "Write in the chat", + "description": "Post a message to the player or spectator chat, in a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "room", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The message was successfully posted in chat.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The posting of the message in chat failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "get": { + "operationId": "botGameChatGet", + "summary": "Fetch the game chat", + "description": "Get the messages posted in the game chat\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "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/GameChat" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/abort": { + "post": { + "operationId": "botGameAbort", + "summary": "Abort a game", + "description": "Abort a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully aborted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The abortion of the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/resign": { + "post": { + "operationId": "botGameResign", + "summary": "Resign a game", + "description": "Resign a game being played with the Bot API.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The game was successfully resigned from.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "Resigning the game failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/draw/{accept}": { + "post": { + "operationId": "botGameDraw", + "summary": "Handle draw offers", + "description": "Create/accept/decline draw offers with the Bot API.\n- `yes`: Offer a draw, or accept the opponent's draw offer.\n- `no`: Decline a draw offer from the opponent.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The draw offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The draw offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bot/game/{gameId}/takeback/{accept}": { + "post": { + "operationId": "botGameTakeback", + "summary": "Handle takeback offers", + "description": "Create/accept/decline takebacks with the Bot API.\n- `yes`: Propose a takeback, or accept the opponent's takeback offer.\n- `no`: Decline a takeback offer from the opponent.\n", + "tags": [ + "Bot" + ], + "security": [ + { + "OAuth2": [ + "bot:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "path", + "name": "accept", + "schema": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "const": "yes" + } + ], + "example": "yes" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The takeback offer was successfully sent.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The takeback offering failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge": { + "get": { + "operationId": "challengeList", + "summary": "List your challenges", + "description": "Get a list of challenges created by or targeted at you.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:read" + ] + } + ], + "responses": { + "200": { + "description": "The list of challenges created by or targeted at the logged in user.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "in": { + "type": "array", + "description": "Incoming challenges i.e. targeted at you", + "items": { + "$ref": "#/components/schemas/ChallengeJson" + } + }, + "out": { + "type": "array", + "description": "Outgoing challenges i.e. created by you", + "items": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + } + } + } + } + } + } + } + }, + "/api/challenge/{username}": { + "post": { + "operationId": "challengeCreate", + "summary": "Create a challenge", + "description": "Challenge someone to play. The targeted player can choose to accept or decline.\nIf the challenge is accepted, you will be notified on the [event stream](#operation/apiStreamEvent)\nthat a new game has started. The game ID will be the same as the challenge ID.\nChallenges for realtime games (not correspondence) expire after 20s if not accepted.\nTo prevent that, use the `keepAliveStream` flag described below.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "LeelaChess" + }, + "required": true + } + ], + "requestBody": { + "description": "Parameters of the challenge", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created. Valid values are 0, 15, 30, 45, 60, 90, and any multiple of 60 up to 10800 (3 hours).", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per move, for correspondence games. Clock settings must be omitted.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "color": { + "type": "string", + "description": "Which color you get to play", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "keepAliveStream": { + "type": "boolean", + "description": "If set, the response is streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON).\nThe challenge is kept alive until the connection is closed by the client.\nWhen the challenge is accepted, declined or canceled, a message of the form `{\"done\":\"accepted\"}` is sent,\nthen the connection is closed by the server.\nIf not set, the response is not streamed, and the challenge expires after 20s if not accepted.\n" + }, + "rules": { + "type": "string", + "enum": [ + "noAbort", + "noRematch", + "noGiveTime", + "noClaimWin", + "noEarlyDraw" + ], + "description": "Extra game rules separated by commas.\nExample: `noAbort,noRematch`\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "challenge": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + } + } + } + }, + "400": { + "description": "The creation of the challenge failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/accept": { + "post": { + "operationId": "challengeAccept", + "summary": "Accept a challenge", + "description": "Accept an incoming challenge.\nYou should receive a `gameStart` event on the [incoming events stream](#operation/apiStreamEvent).\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The challenge was successfully accepted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to accept was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/decline": { + "post": { + "operationId": "challengeDecline", + "summary": "Decline a challenge", + "description": "Decline an incoming challenge.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "requestBody": { + "description": "Details related to decline of challenge", + "required": false, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "description": "Reason challenge was declined. It will be translated to the player's language. See [the full list in the translation file](https://github.com/ornicar/lila/blob/master/translation/source/challenge.xml#L14).", + "enum": [ + "generic", + "later", + "tooFast", + "tooSlow", + "timeControl", + "rated", + "casual", + "standard", + "variant", + "noBot", + "onlyBot" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully declined.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to decline was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/{challengeId}/cancel": { + "post": { + "operationId": "challengeCancel", + "summary": "Cancel a challenge", + "description": "Cancel a challenge you sent, or aborts the game if the challenge was accepted, but the game was not yet played.\nNote that the ID of a game is the same as the ID of the challenge that created it.\nWorks for user challenges and open challenges alike.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "challengeId", + "schema": { + "type": "string", + "example": "5IrD6Gzz" + }, + "required": true + }, + { + "in": "query", + "name": "opponentToken", + "description": "Optional `challenge:write` token of the opponent. If set, the game can be canceled even if both players have moved.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The challenge was successfully cancelled.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The challenge to cancel was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/challenge/ai": { + "post": { + "operationId": "challengeAi", + "summary": "Challenge the AI", + "description": "Start a game with Lichess AI.\nYou will be notified on the [event stream](#operation/apiStreamEvent) that a new game has started.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write", + "bot:play", + "board:play" + ] + } + ], + "requestBody": { + "description": "Parameters of the game", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "level": { + "type": "number", + "description": "AI strength", + "minimum": 1, + "maximum": 8 + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created.", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per move, for correspondence games. Clock settings must be omitted.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "color": { + "type": "string", + "description": "Which color you get to play", + "enum": [ + "random", + "white", + "black" + ], + "default": "random" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "The game with Lichess AI was successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GameJson" + } + } + } + }, + "400": { + "description": "The creation of a game with Lichess AI failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/open": { + "post": { + "operationId": "challengeOpen", + "summary": "Open-ended challenge", + "description": "Create a challenge that any 2 players can join.\nShare the URL of the challenge. the first 2 players to click it will be paired for a game.\nThe response body also contains `whiteUrl` and `blackUrl`.\nYou can control which color each player gets by giving them these URLs,\ninstead of the main challenge URL.\nOpen challenges expire after 24h.\nIf the challenge creation is [authenticated with OAuth2](#section/Introduction/Authentication),\nthen you can use the [challenge cancel endpoint](#operation/challengeCancel) to cancel it.\nTo directly pair 2 known players, use [this endpoint](#operation/bulkPairingList) instead.\n", + "tags": [ + "Challenges" + ], + "security": [], + "requestBody": { + "description": "Parameters of the game", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. If empty, a correspondence game is created.", + "example": 300, + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. If empty, a correspondence game is created.", + "example": 1, + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per turn. For correspondence challenges.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "name": { + "type": "string", + "description": "Optional name for the challenge, that players will see on the challenge page." + }, + "rules": { + "type": "string", + "enum": [ + "noRematch", + "noGiveTime", + "noClaimWin", + "noEarlyDraw", + "noAbort" + ], + "description": "Extra game rules separated by commas.\nExample: `noRematch,noGiveTime`\nThe `noAbort` rule is available for Lichess admins only\n" + }, + "users": { + "type": "string", + "description": "Optional pair of usernames, separated by a comma.\nIf set, only these users will be allowed to join the game.\nThe first username gets the white pieces.\nExample: `Username1,Username2`\n" + }, + "expiresAt": { + "type": "integer", + "description": "Timestamp in milliseconds to expire the challenge. Defaults to 24h after creation. Can't be more than 2 weeks after creation." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The challenge was successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChallengeOpenJson" + } + } + } + }, + "400": { + "description": "The creation of the challenge failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/challenge/{gameId}/start-clocks": { + "post": { + "operationId": "challengeStartClocks", + "summary": "Start clocks of a game", + "description": "Start the clocks of a game immediately, even if a player has not yet made a move.\nRequires the OAuth tokens of both players with `challenge:write` scope.\nIf the clocks have already started, the call will have no effect.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "description": "ID of the game" + }, + "required": true + }, + { + "in": "query", + "name": "token1", + "description": "OAuth token of a player", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "token2", + "description": "OAuth token of the other player", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The clock of a game was successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/bulk-pairing": { + "get": { + "operationId": "bulkPairingList", + "summary": "View your bulk pairings", + "description": "Get a list of bulk pairings you created.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "responses": { + "200": { + "description": "The list of bulk pairing the logged in user created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkPairing" + } + } + } + } + } + } + }, + "post": { + "operationId": "bulkPairingCreate", + "summary": "Create a bulk pairing", + "description": "Schedule many games at once, up to 24h in advance.\nOAuth tokens are required for all paired players, with the `challenge:write` scope.\nYou can schedule up to 500 games every 10 minutes. [Contact us](mailto:contact@lichess.org) if you need higher limits.\nIf games have a real-time clock, each player must have only one pairing.\nFor correspondence games, players can have multiple pairings within the same bulk.\nThe entire bulk is rejected if:\n - a token is missing\n - a token is present more than once (except in correspondence)\n - a token lacks the `challenge:write` scope\n - a player account is closed\n - a player is paired more than once (except in correspondence)\n - a bulk is already scheduled to start at the same time with the same player\n - you have 20 scheduled bulks\n - you have 1000 scheduled games\nPartial bulks are never created. Either it all fails, or it all succeeds.\nWhen it fails, it does so with an error message explaining the issue.\nFailed bulks are not counted in the rate limiting, they are free.\nFix the issues, manually or programmatically, then retry to schedule the bulk.\nA successful bulk creation returns a JSON bulk document. Its ID can be used for further operations.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "requestBody": { + "description": "Parameters of the pairings", + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "players": { + "type": "string", + "description": "OAuth tokens of all the players to pair, with the syntax `tokenOfWhitePlayerInGame1:tokenOfBlackPlayerInGame1,tokenOfWhitePlayerInGame2:tokenOfBlackPlayerInGame2,...`.\nThe 2 tokens of the players of a game are separated with `:`. The first token gets the white pieces. Games are separated with `,`.\nUp to 1000 tokens can be sent, for a max of 500 games.\nEach token must be included at most once.\nExample: `token1:token2,token3:token4,token5:token6`\n" + }, + "clock.limit": { + "type": "number", + "description": "Clock initial time in seconds. Example: `600`\n", + "minimum": 0, + "maximum": 10800 + }, + "clock.increment": { + "type": "integer", + "description": "Clock increment in seconds. Example: `2`\n", + "minimum": 0, + "maximum": 60 + }, + "days": { + "type": "integer", + "description": "Days per turn. For correspondence games only.", + "enum": [ + 1, + 2, + 3, + 5, + 7, + 10, + 14 + ] + }, + "pairAt": { + "description": "Date at which the games will be created as a Unix timestamp in milliseconds.\nUp to 7 days in the future.\nOmit, or set to current date and time, to start the games immediately.\nExample: `1612289869919`\n", + "type": "integer" + }, + "startClocksAt": { + "description": "Date at which the clocks will be automatically started as a Unix timestamp in milliseconds.\nUp to 7 days in the future.\nNote that the clocks can start earlier than specified, if players start making moves in the game.\nIf omitted, the clocks will not start automatically.\nExample: `1612289869919`\n", + "type": "integer" + }, + "rated": { + "type": "boolean", + "description": "Game is rated and impacts players ratings", + "default": false + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "fen": { + "$ref": "#/components/schemas/FromPositionFEN" + }, + "message": { + "type": "string", + "description": "Message that will be sent to each player, when the game is created. It is sent from your user account.\n`{opponent}` and `{game}` are placeholders that will be replaced with the opponent and the game URLs.\nYou can omit this field to send the default message,\nbut if you set your own message, it must at least contain the `{game}` placeholder.\n", + "default": "Your game with {opponent} is ready: {game}." + }, + "rules": { + "type": "string", + "enum": [ + "noAbort", + "noRematch", + "noGiveTime", + "noClaimWin", + "noEarlyDraw" + ], + "description": "Extra game rules separated by commas.\nExample: `noAbort,noRematch`\n" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The bulk pairing has been successfully created.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkPairing" + } + } + } + }, + "400": { + "description": "The creation of the bulk pairings failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/bulk-pairing/{id}/start-clocks": { + "post": { + "operationId": "bulkPairingStartClocks", + "summary": "Manually start clocks", + "description": "Immediately start all clocks of the games of a bulk pairing.\nThis overrides the `startClocksAt` value of an existing bulk pairing.\nIf the games have not yet been created (`bulk.pairAt` is in the future), then this does nothing.\nIf the clocks have already started (`bulk.startClocksAt` is in the past), then this does nothing.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The ID of the bulk pairing", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The clocks of the games of a bulk pairing were successfully started.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The bulk pairing was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/bulk-pairing/{id}": { + "get": { + "operationId": "bulkPairingGet", + "summary": "Show a bulk pairing", + "description": "Get a single bulk pairing by its ID.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The ID of the bulk pairing", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The bulk pairing.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkPairing" + } + } + } + }, + "404": { + "description": "The bulk pairing was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + }, + "delete": { + "operationId": "bulkPairingDelete", + "summary": "Cancel a bulk pairing", + "description": "Cancel and delete a bulk pairing that is scheduled in the future.\nIf the games have already been created, then this does nothing.\nCanceling a bulk pairing does not refund the rate limit cost of that bulk pairing.\n", + "tags": [ + "Bulk pairings" + ], + "security": [ + { + "OAuth2": [ + "challenge:bulk" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The ID of the bulk pairing", + "example": "5IrD6Gzz" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The bulk pairing was successfully deleted.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "404": { + "description": "The bulk pairing to delete was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NotFound" + } + } + } + } + } + } + }, + "/api/round/{gameId}/add-time/{seconds}": { + "post": { + "operationId": "roundAddTime", + "summary": "Add time to the opponent clock", + "description": "Add seconds to the opponent's clock. Can be used to create games with time odds.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "challenge:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string", + "description": "ID of the game" + }, + "required": true + }, + { + "in": "path", + "name": "seconds", + "description": "How many seconds to give", + "schema": { + "type": "string", + "minimum": 1, + "maximum": 86400 + }, + "required": true + } + ], + "responses": { + "200": { + "description": "Time was successfully added to the opponent's clock.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/token/admin-challenge": { + "post": { + "operationId": "adminChallengeTokens", + "summary": "Admin challenge tokens", + "description": "**This endpoint can only be used by Lichess administrators. It will not work if you do not have the appropriate permissions.** Tournament organizers should instead use [OAuth](#tag/OAuth) to obtain `challenge:write` tokens from users in order to perform bulk pairing.*\nCreate and obtain `challenge:write` tokens for multiple users.\nIf a similar token already exists for a user, it is reused. This endpoint is idempotent.\n", + "tags": [ + "Challenges" + ], + "security": [ + { + "OAuth2": [ + "web:mod" + ] + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "users": { + "description": "Usernames separated with commas", + "type": "string", + "example": "thibault,neio,lizen2,lizen3" + }, + "description": { + "description": "User visible description of the token", + "type": "string", + "example": "FIDE tournament XYZ" + } + }, + "required": [ + "users", + "description" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The `challenge:write` tokens of each user", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "thibault": "lLOEkpH58W599xH9", + "neio": "nAYTIJphwWFwKmKk", + "lizen2": "1cnHhuWKHROgiPC4", + "lizen3": "SszJ9Sj1bto0UQCK" + } + } + } + }, + "400": { + "description": "The creation of the tokens failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/inbox/{username}": { + "post": { + "operationId": "inboxUsername", + "summary": "Send a private message", + "description": "Send a private message to another player.\n", + "tags": [ + "Messaging" + ], + "security": [ + { + "OAuth2": [ + "msg:write" + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "username", + "schema": { + "type": "string", + "example": "someplayer" + }, + "required": true + } + ], + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "text": { + "type": "string", + "example": "Thank you for the game!" + } + }, + "required": [ + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "The private message has been successfully sent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "400": { + "description": "The sending of the private message has failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/cloud-eval": { + "get": { + "operationId": "apiCloudEval", + "summary": "Get cloud evaluation of a position.", + "description": "Get the cached evaluation of a position, if available.\nOpening positions have more chances of being available. There are about 15 million positions in the database.\nUp to 5 variations may be available. Variants are supported.\nUse this endpoint to fetch a few positions here and there.\nIf you want to download a lot of positions, [get the full list](https://database.lichess.org/#evals) from our exported database.\n", + "tags": [ + "Analysis" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "required": true, + "description": "FEN of the position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2" + }, + { + "in": "query", + "name": "multiPv", + "description": "Number of variations", + "schema": { + "type": "number", + "default": 1 + } + }, + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey" + } + } + ], + "responses": { + "200": { + "description": "The evaluation of the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "fen": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2", + "knodes": 13683, + "depth": 22, + "pvs": [ + { + "moves": "c8f5 d2d4 e7e6 g1f3 g8e7 c1e3 c7c5 d4c5 e7c6 b1c3", + "cp": -13 + }, + { + "moves": "c7c5 c2c3 d5d4 g1f3 b8c6 c3d4 c6d4 b1c3 c8d7 f1d3", + "cp": -1 + }, + { + "moves": "e7e6 d2d4 c7c5 c2c3 b8c6 g1f3 c8d7 b1a3 c5d4 c3d4", + "cp": 24 + } + ] + } + } + } + } + } + } + }, + "/api/external-engine": { + "get": { + "operationId": "apiExternalEngineList", + "summary": "List external engines", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:read" + ] + } + ], + "description": "Lists all external engines that have been registered for the user,\nand the credentials required to use them.\n", + "responses": { + "200": { + "description": "A list of external engines.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + } + }, + "post": { + "operationId": "apiExternalEngineCreate", + "summary": "Create external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Registers a new external engine for the user. It can then be selected\nand used on the analysis board.\nAfter registering, the provider should start waiting for analyis requests.\n", + "requestBody": { + "description": "A new external engine registration.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngineRegistration" + } + } + } + }, + "responses": { + "200": { + "description": "The registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + } + }, + "/api/external-engine/{id}": { + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The external engine id.", + "schema": { + "type": "string" + }, + "example": "eei_aTKImBJOnv6j" + } + ], + "get": { + "operationId": "apiExternalEngineGet", + "summary": "Get external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:read" + ] + } + ], + "description": "Get properties and credentials of an external engine.\n", + "responses": { + "200": { + "description": "A registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + }, + "put": { + "operationId": "apiExternalEnginePut", + "summary": "Update external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Updates the properties of an external engine.\n", + "requestBody": { + "description": "A modified engine registration.", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngineRegistration" + } + } + } + }, + "responses": { + "200": { + "description": "A registered engine.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExternalEngine" + } + } + } + } + } + }, + "delete": { + "operationId": "apiExternalEngineDelete", + "summary": "Delete external engine", + "tags": [ + "External engine" + ], + "security": [ + { + "OAuth2": [ + "engine:write" + ] + } + ], + "description": "Unregisters an external engine.\n", + "responses": { + "200": { + "description": "Engine successfully deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + } + } + } + }, + "/api/external-engine/{id}/analyse": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "description": "The external engine id.", + "schema": { + "type": "string" + }, + "example": "eei_aTKImBJOnv6j" + } + ], + "post": { + "operationId": "apiExternalEngineAnalyse", + "summary": "Analyse with external engine", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/{id}/analyse`**\nRequest analysis from an external engine.\nResponse content is streamed as [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON).\nThe properties are based on the [UCI specification](https://backscattering.de/chess/uci/#engine).\nAnalysis stops when the client goes away, the requested limit\nis reached, or the provider goes away.\n", + "requestBody": { + "description": "Engine credentials and analysis request.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "clientSecret": { + "type": "string", + "example": "ees_mdF2hK0hlKGSPeC6" + }, + "work": { + "$ref": "#/components/schemas/ExternalEngineWork" + } + }, + "required": [ + "clientSecret", + "work" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Stream of analysis output", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-ndjson": { + "schema": { + "type": "object", + "properties": { + "time": { + "type": "integer", + "description": "Number of milliseconds the search has been going on", + "example": 6880, + "minimum": 0 + }, + "depth": { + "type": "integer", + "description": "Current search depth", + "example": 25, + "minimum": 0 + }, + "nodes": { + "type": "integer", + "description": "Number of nodes visited so far", + "example": 7230340, + "minimum": 0 + }, + "pvs": { + "type": "array", + "description": "Information about up to 5 pvs, with the primary pv at index 0.", + "items": { + "type": "object", + "properties": { + "depth": { + "type": "integer", + "description": "Current search depth of the pv", + "example": 25, + "minimum": 0 + }, + "cp": { + "type": "integer", + "description": "Evaluation in centi-pawns, from White's point of view", + "example": 40 + }, + "mate": { + "type": "integer", + "description": "Evaluation in signed moves to mate, from White's point of view" + }, + "moves": { + "type": "array", + "description": "Variation in UCI notation", + "items": { + "type": "string" + }, + "example": [ + "e2e4", + "c7c6", + "g1f3", + "d7d5", + "d2d3", + "d5e4" + ] + } + }, + "required": [ + "depth", + "moves" + ] + } + } + }, + "required": [ + "time", + "depth", + "nodes", + "pvs" + ] + } + } + } + } + } + } + }, + "/api/external-engine/work": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "post": { + "operationId": "apiExternalEngineAcquire", + "summary": "Acquire analysis request", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/work`**\nWait for an analysis requests to any of the external engines that\nhave been registered with the given `secret`.\nUses long polling.\nAfter acquiring a request, the provider should immediately\n[start streaming the results](#tag/External-engine/operation/apiExternalEngineSubmit).\n", + "requestBody": { + "description": "Provider credentials.", + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "providerSecret": { + "type": "string", + "example": "Dee3uwieZei9ahpaici9bee2yahsai0K" + } + }, + "required": [ + "secret" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Analysis has been requested", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "aingoohiJee2sius" + }, + "work": { + "$ref": "#/components/schemas/ExternalEngineWork" + }, + "engine": { + "$ref": "#/components/schemas/ExternalEngine" + } + }, + "required": [ + "id", + "engine", + "work" + ] + } + } + } + }, + "204": { + "description": "No pending analysis", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/api/external-engine/work/{id}": { + "servers": [ + { + "url": "https://engine.lichess.ovh" + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "type": "string", + "example": "aingoohiJee2sius" + } + } + ], + "post": { + "operationId": "apiExternalEngineSubmit", + "summary": "Answer analysis request", + "tags": [ + "External engine" + ], + "security": [], + "description": "**Endpoint: `https://engine.lichess.ovh/api/external-engine/work/{id}`**\nSubmit a stream of analysis as [UCI output](https://backscattering.de/chess/uci/#engine-info).\n* The engine should always be in `UCI_Chess960` mode.\n* `UCI_AnalyseMode` enabled if available.\n* It produces `info` with at least:\n - `depth`\n - `multipv` (between 1 and 5)\n - `score`\n - `nodes`\n - `time`\n - `pv`\nThe server may close the connection at any time, indicating that\nthe requester has gone away and analysis should be stopped.\n", + "requestBody": { + "description": "Analysis results", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "info multipv 1 depth 20 seldepth 30 time 1373 nodes 1494341 score cp 47 hashfull 594 nps 1088376 tbhits 0 pv d2d4 d7d5 c2c4 e7e6 b1c3 f8b4 c4d5 e6d5 g1f3 g8f6 c1g5 h7h6 g5f6 d8f6 d1b3 c7c5 e2e3 b8c6 d4c5 e8g8 f1d3" + } + } + }, + "responses": { + "200": { + "description": "Thanks", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/oauth": { + "get": { + "operationId": "oauth", + "summary": "Request authorization code", + "tags": [ + "OAuth" + ], + "security": [], + "description": "OAuth2 authorization endpoint.\nStart the OAuth2 Authorization Code Flow with PKCE by securely\ngenerating two random strings unique to each authorization\nrequest:\n* `code_verifier`\n* `state`\nStore these in session storage. Make sure not to reveal `code_verifier`\nto eavesdroppers. Do not show it in URLs, do not abuse `state` to store\nit, do not send it over insecure connections. However it is fine if\nthe user themselves can extract `code_verifier`, which will always be\npossible for fully client-side apps.\nThen send the user to this endpoint. They will be prompted to grant\nauthorization and then be redirected back to the given `redirect_uri`.\nIf the authorization failed, the following query string parameters will\nbe appended to the redirection:\n* `error`, in particular with value `access_denied` if the user\n cancelled authorization\n* `error_description` to aid debugging\n* `state`, exactly as passed in the `state` parameter\nIf the authorization succeeded, the following query string parameters\nwill be appended to the redirection:\n* `code`, containing a fresh short-lived authorization code\n* `state`, exactly as passed in the `state` parameter\nNext, to defend against cross site request forgery, check that the\nreturned `state` matches the `state` you originally generated.\nFinally, continue by using the authorization code to\n[obtain an access token](#operation/apiToken).\n", + "parameters": [ + { + "in": "query", + "name": "response_type", + "description": "Must be `code`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "client_id", + "description": "Arbitrary identifier that uniquely identifies your application.", + "example": "example.com", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "redirect_uri", + "description": "The absolute URL that the user should be redirected to with the authorization result.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "code_challenge_method", + "description": "Must be `S256`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "code_challenge", + "description": "Compute `BASE64URL(SHA256(code_verifier))`.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "scope", + "description": "Space separated list of requested OAuth scopes, if any.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "username", + "description": "Hint that you want the user to log in with a specific Lichess username.", + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "state", + "description": "Arbitrary state that will be returned verbatim with the authorization result.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Authorization prompt will be displayed to the user." + } + } + } + }, + "/api/token": { + "post": { + "operationId": "apiToken", + "summary": "Obtain access token", + "tags": [ + "OAuth" + ], + "security": [], + "description": "OAuth2 token endpoint. Exchanges an authorization code for an access token.\n", + "requestBody": { + "required": true, + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "properties": { + "grant_type": { + "type": "string", + "example": "authorization_code", + "description": "Must be `authorization_code`." + }, + "code": { + "type": "string", + "example": "liu_iS1uOZg99Htmo58ex2jKgYziUfzsnAl0", + "description": "The authorization code that was sent in the `code` parameter to your `redirect_uri`." + }, + "code_verifier": { + "type": "string", + "example": "Ry1rbGdOMTQtUjhOc0lmTnFKak1LTHV0NjlRMll2aXYtTThkQnlJRkRpaGwyQjh0ZDNFdzFPSG9KUlY4M1NrRzJ5ZHhUdjVZR08zLTZOT3dCN2xLfjZOXzU2WHk4SENP", + "description": "A `code_challenge` was used to request the authorization code. This must be the `code_verifier` it was derived from." + }, + "redirect_uri": { + "type": "string", + "example": "http://example.com/", + "description": "Must match the `redirect_uri` used to request the authorization code." + }, + "client_id": { + "type": "string", + "example": "example.com", + "description": "Must match the `client_id` used to request the authorization code." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Access token successfully obtained.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "example": { + "token_type": "Bearer", + "access_token": "lio_pLwAbN7lFPklzY2m8lTOI1DGApS84u57", + "expires_in": 31536000 + } + } + } + }, + "400": { + "description": "Failed to obtain access token.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthError" + } + } + } + } + } + }, + "delete": { + "operationId": "apiTokenDelete", + "summary": "Revoke access token", + "description": "Revokes the access token sent as Bearer for this request.", + "tags": [ + "OAuth" + ], + "security": [ + { + "OAuth2": [] + } + ], + "responses": { + "204": { + "description": "Access token revoked.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/api/token/test": { + "post": { + "operationId": "tokenTest", + "summary": "Test multiple OAuth tokens", + "description": "For up to 1000 OAuth tokens,\nreturns their associated user ID and scopes,\nor `null` if the token is invalid.\nThe method is `POST` so a longer list of tokens can be sent in the request body.\n", + "tags": [ + "OAuth" + ], + "security": [], + "requestBody": { + "description": "OAuth tokens separated by commas. Up to 1000.", + "required": true, + "content": { + "text/plain": { + "schema": { + "type": "string" + }, + "example": "lip_AvsS88TozFeSMEaoLN5c,lip_badToken" + } + } + }, + "responses": { + "200": { + "description": "The representation of the OAuth tokens.", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "x-additionalPropertiesName": "token", + "oneOf": [ + { + "type": "object", + "properties": { + "userId": { + "type": "string" + }, + "scopes": { + "type": "string", + "description": "Comma-separated list of scopes. Empty string if the token has no scopes." + }, + "expires": { + "type": [ + "integer", + null + ], + "description": "Unix-timestampe in milliseconds or null if the token never expires." + } + } + }, + { + "type": null + } + ] + }, + "example": { + "lip_AvsS88TozFeSnZa1LN5c": { + "scopes": "challenge:read,challenge:write", + "userId": "thibault", + "expires": 1358509698620 + }, + "lip_badToken": null + } + } + } + } + } + } + } + }, + "/masters": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerMaster", + "summary": "Masters database", + "description": "**Endpoint: <https://explorer.lichess.ovh/masters>**\nExample: `curl https://explorer.lichess.ovh/masters?play=d2d4,d7d5,c2c4,c7c6,c4d5`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "e2e4,e7e5,c2c4,c7c6,c4e5" + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this year or later", + "schema": { + "type": "number", + "default": 1952 + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this year or earlier", + "schema": { + "type": "number" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number", + "default": 12 + } + }, + { + "in": "query", + "name": "topGames", + "description": "Number of top games to display", + "schema": { + "type": "number", + "default": 15, + "maximum": 15 + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerJson" + } + } + } + } + } + } + }, + "/lichess": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerLichess", + "summary": "Lichess games", + "description": "**Endpoint: <https://explorer.lichess.ovh/lichess>**\nGames sampled from all Lichess players.\nExample: `curl https://explorer.lichess.ovh/lichess?variant=standard&speeds=blitz,rapid,classical&ratings=2200,2500&fen=rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR%20w%20KQkq%20-%200%201`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey", + "default": "standard" + } + }, + { + "in": "query", + "name": "fen", + "description": "FEN or EPD of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR b KQkq - 0 2" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "e2e4,e7e5,c2c4,c7c6,c4e5" + }, + { + "in": "query", + "name": "speeds", + "description": "Comma separated list of game speeds to filter by", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Speed" + } + } + }, + { + "in": "query", + "name": "ratings", + "description": "Comma separated list of ratings groups to filter by.\nEach group ranges from its value to the next higher\ngroup in the enum (`0` from 0 to 999, `1000` from 1000 to 1199,\n..., `2500` from 2500 to any rating above).\n", + "schema": { + "type": "array", + "items": { + "type": "number", + "enum": [ + 0, + 1000, + 1200, + 1400, + 1600, + 1800, + 2000, + 2200, + 2500 + ] + } + } + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this month or later", + "schema": { + "type": "string", + "default": "1952-01" + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this month or earlier", + "schema": { + "type": "string", + "default": "3000-12" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number", + "default": 12 + } + }, + { + "in": "query", + "name": "topGames", + "description": "Number of top games to display", + "schema": { + "type": "number", + "default": 4, + "maximum": 4 + } + }, + { + "in": "query", + "name": "recentGames", + "description": "Number of recent games to display", + "schema": { + "type": "number", + "default": 4, + "maximum": 4 + } + }, + { + "in": "query", + "name": "history", + "description": "Optionally retrieve history", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerJson" + } + } + } + } + } + } + }, + "/player": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerPlayer", + "summary": "Player games", + "description": "**Endpoint: <https://explorer.lichess.ovh/player>**\nGames of a Lichess player.\nResponds with a stream of [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). Will start indexing\non demand, immediately respond with the current results, and stream\nmore updates until indexing is complete. The stream is throttled\nand deduplicated. Empty lines may be sent to avoid timeouts.\nWill index new games at most once per minute, and revisit previously\nongoing games at most once every day.\nExample: `curl https://explorer.lichess.ovh/player?player=revoof&color=white&play=d2d4,d7d5&recentGames=1`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "player", + "description": "Username or ID of the player", + "schema": { + "type": "string" + }, + "example": "revoof" + }, + { + "in": "query", + "name": "variant", + "description": "Variant", + "schema": { + "$ref": "#/components/schemas/VariantKey", + "default": "standard" + } + }, + { + "in": "query", + "name": "fen", + "description": "FEN of the root position", + "schema": { + "type": "string" + }, + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + { + "in": "query", + "name": "play", + "description": "Comma separated sequence of legal moves in UCI notation.\nPlay additional moves starting from `fen`.\nRequired to find an opening name, if `fen` is not an exact match\nfor a named position.\n", + "schema": { + "type": "string", + "default": "" + }, + "example": "d2d4,d7d5" + }, + { + "in": "query", + "name": "speeds", + "description": "Comma separated list of game speeds to look for", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Speed" + } + } + }, + { + "in": "query", + "name": "modes", + "description": "Comma separated list of modes", + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "casual", + "rated" + ] + } + } + }, + { + "in": "query", + "name": "since", + "description": "Include only games from this month or later", + "schema": { + "type": "string", + "default": "1952-01" + } + }, + { + "in": "query", + "name": "until", + "description": "Include only games from this month or earlier", + "schema": { + "type": "string", + "default": "3000-12" + } + }, + { + "in": "query", + "name": "moves", + "description": "Number of most common moves to display", + "schema": { + "type": "number" + } + }, + { + "in": "query", + "name": "recentGames", + "description": "Number of recent games to display", + "schema": { + "type": "number", + "default": 8, + "maximum": 8 + } + } + ], + "responses": { + "200": { + "description": "Opening statistics and game references for the position.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/nd-json": { + "schema": { + "$ref": "#/components/schemas/OpeningExplorerPlayerJson" + } + } + } + } + } + } + }, + "/master/pgn/{gameId}": { + "servers": [ + { + "url": "https://explorer.lichess.ovh" + } + ], + "get": { + "operationId": "openingExplorerMasterGame", + "summary": "OTB master game", + "description": "**Endpoint: `https://explorer.lichess.ovh/masters/pgn/{gameId}`**\nExample: `curl https://explorer.lichess.ovh/masters/pgn/aAbqI4ey`\n", + "tags": [ + "Opening Explorer" + ], + "security": [], + "parameters": [ + { + "in": "path", + "name": "gameId", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The PGN representation of the game.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/x-chess-pgn": { + "schema": { + "$ref": "#/components/schemas/MasterGamePgn" + } + } + } + } + } + } + }, + "/standard": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "tablebaseStandard", + "summary": "Tablebase lookup", + "description": "**Endpoint: <https://tablebase.lichess.ovh>**\nExample: `curl http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1`\n", + "tags": [ + "Tablebase" + ], + "security": [], + "parameters": [ + { + "in": "query", + "name": "fen", + "description": "FEN of the position. Underscores allowed.", + "schema": { + "type": "string" + }, + "required": true + } + ], + "responses": { + "200": { + "description": "The tablebase information for the position in standard chess.", + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TablebaseJson" + } + } + } + } + } + } + }, + "/atomic": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "tablebaseAtomic", + "summary": "Tablebase lookup for Atomic chess", + "description": "**Endpoint: <https://tablebase.lichess.ovh>**\n", + "tags": [ + "Tablebase" + ], + "security": [], + "responses": { + "200": { + "description": "The tablebase information for the position in atomic chess.", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + }, + "/antichess": { + "servers": [ + { + "url": "https://tablebase.lichess.ovh" + } + ], + "get": { + "operationId": "antichessAtomic", + "summary": "Tablebase lookup for Antichess", + "description": "**Endpoint: <https://tablebase.lichess.ovh>**\n", + "tags": [ + "Tablebase" + ], + "security": [], + "responses": { + "200": { + "description": "The tablebase information for the position in antichess.", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "headers": { + "Access-Control-Allow-Origin": { + "schema": { + "type": "string", + "default": "'*'" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Top10s": { + "example": { + "bullet": [ + { + "id": "bahadirozen", + "username": "BahadirOzen", + "perfs": { + "bullet": { + "rating": 3018, + "progress": 18 + } + }, + "online": true, + "title": "FM" + }, + { + "id": "penguingim1", + "username": "penguingim1", + "perfs": { + "bullet": { + "rating": 2983, + "progress": -36 + } + }, + "title": "GM", + "online": true, + "patron": true + }, + { + "id": "night-king96", + "username": "Night-King96", + "perfs": { + "bullet": { + "rating": 2958, + "progress": 35 + } + }, + "title": "GM" + } + ], + "blitz": [], + "rapid": [], + "classical": [], + "ultraBullet": [], + "chess960": [], + "crazyhouse": [], + "antichess": [], + "atomic": [], + "horde": [], + "kingOfTheHill": [], + "racingKings": [], + "threeCheck": [] + } + }, + "Leaderboard": { + "example": { + "users": [ + { + "id": "bahadirozen", + "username": "BahadirOzen", + "perfs": { + "bullet": { + "rating": 3018, + "progress": 18 + } + }, + "online": true, + "title": "FM" + }, + { + "id": "penguingim1", + "username": "penguingim1", + "perfs": { + "bullet": { + "rating": 2983, + "progress": -36 + } + }, + "title": "GM", + "online": true, + "patron": true + }, + { + "id": "night-king96", + "username": "Night-King96", + "perfs": { + "bullet": { + "rating": 2958, + "progress": 35 + } + }, + "title": "GM" + } + ] + } + }, + "Perf": { + "type": "object", + "properties": { + "games": { + "type": "integer", + "example": 2945 + }, + "rating": { + "type": "integer", + "example": 1609 + }, + "rd": { + "type": "integer", + "example": 60 + }, + "prog": { + "type": "integer", + "example": -22 + }, + "prov": { + "type": "boolean", + "description": "only appears if a user's perf rating are [provisional](https://lichess.org/faq#provisional)" + } + } + }, + "PuzzleModePerf": { + "type": "object", + "properties": { + "runs": { + "type": "integer", + "example": 44 + }, + "score": { + "type": "integer", + "example": 61 + } + } + }, + "Perfs": { + "type": "object", + "properties": { + "chess960": { + "$ref": "#/components/schemas/Perf" + }, + "atomic": { + "$ref": "#/components/schemas/Perf" + }, + "racingKings": { + "$ref": "#/components/schemas/Perf" + }, + "ultraBullet": { + "$ref": "#/components/schemas/Perf" + }, + "blitz": { + "$ref": "#/components/schemas/Perf" + }, + "kingOfTheHill": { + "$ref": "#/components/schemas/Perf" + }, + "bullet": { + "$ref": "#/components/schemas/Perf" + }, + "correspondence": { + "$ref": "#/components/schemas/Perf" + }, + "horde": { + "$ref": "#/components/schemas/Perf" + }, + "puzzle": { + "$ref": "#/components/schemas/Perf" + }, + "classical": { + "$ref": "#/components/schemas/Perf" + }, + "rapid": { + "$ref": "#/components/schemas/Perf" + }, + "storm": { + "$ref": "#/components/schemas/PuzzleModePerf" + }, + "racer": { + "$ref": "#/components/schemas/PuzzleModePerf" + }, + "streak": { + "$ref": "#/components/schemas/PuzzleModePerf" + } + } + }, + "Profile": { + "type": "object", + "properties": { + "country": { + "type": "string", + "example": "EC" + }, + "location": { + "type": "string" + }, + "bio": { + "type": "string", + "example": "Free bugs!" + }, + "firstName": { + "type": "string", + "example": "Thibault" + }, + "lastName": { + "type": "string", + "example": "Duplessis" + }, + "fideRating": { + "type": "integer", + "example": 1500, + "description": "only appears if a user has set them" + }, + "uscfRating": { + "type": "integer", + "example": 1500, + "description": "only appears if a user has set them" + }, + "ecfRating": { + "type": "integer", + "example": 1500, + "description": "only appears if a user has set them" + }, + "cfcRating": { + "type": "integer", + "example": 1500, + "description": "only appears if a user has set them" + }, + "dsbRating": { + "type": "integer", + "example": 1500, + "description": "only appears if a user has set them" + }, + "links": { + "type": "string", + "example": "github.com/ornicar\r\ntwitter.com/ornicar" + } + } + }, + "PlayTime": { + "type": "object", + "properties": { + "total": { + "type": "integer", + "example": 3296897 + }, + "tv": { + "type": "integer", + "example": 12134 + } + } + }, + "Title": { + "type": "string", + "enum": [ + "GM", + "WGM", + "IM", + "WIM", + "FM", + "WFM", + "NM", + "CM", + "WCM", + "WNM", + "LM", + "BOT" + ], + "example": "NM", + "description": "only appears if the user is a titled player or a bot user" + }, + "User": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "georges" + }, + "username": { + "type": "string", + "example": "Georges" + }, + "perfs": { + "$ref": "#/components/schemas/Perfs" + }, + "flair": { + "type": "string", + "example": "nature.water-wave" + }, + "createdAt": { + "type": "integer", + "format": "int64", + "example": 1290415680000 + }, + "disabled": { + "type": "boolean", + "example": false, + "description": "only appears if a user's account is closed" + }, + "tosViolation": { + "type": "boolean", + "example": false, + "description": "only appears if a user's account is marked for the violation of [Lichess TOS](https://lichess.org/terms-of-service)" + }, + "profile": { + "$ref": "#/components/schemas/Profile" + }, + "seenAt": { + "type": "integer", + "format": "int64", + "example": 1522636452014 + }, + "patron": { + "type": "boolean", + "example": true + }, + "verified": { + "type": "boolean", + "example": true + }, + "playTime": { + "$ref": "#/components/schemas/PlayTime" + }, + "title": { + "$ref": "#/components/schemas/Title" + } + } + }, + "Count": { + "type": "object", + "properties": { + "all": { + "type": "integer", + "example": 9265 + }, + "rated": { + "type": "integer", + "example": 7157 + }, + "ai": { + "type": "integer", + "example": 531 + }, + "draw": { + "type": "integer", + "example": 340 + }, + "drawH": { + "type": "integer", + "example": 331 + }, + "loss": { + "type": "integer", + "example": 4480 + }, + "lossH": { + "type": "integer", + "example": 4207 + }, + "win": { + "type": "integer", + "example": 4440 + }, + "winH": { + "type": "integer", + "example": 4378 + }, + "bookmark": { + "type": "integer", + "example": 71 + }, + "playing": { + "type": "integer", + "example": 6 + }, + "import": { + "type": "integer", + "example": 66 + }, + "me": { + "type": "integer", + "example": 0 + } + } + }, + "UserExtended": { + "allOf": [ + { + "$ref": "#/components/schemas/User" + }, + { + "properties": { + "url": { + "type": "string", + "format": "uri", + "example": "https://lichess.org/@/georges" + }, + "playing": { + "type": "string", + "format": "uri", + "example": "https://lichess.org/yqfLYJ5E/black" + }, + "count": { + "$ref": "#/components/schemas/Count" + }, + "streaming": { + "type": "boolean", + "example": false + }, + "streamer": { + "example": { + "twitch": { + "channel": "https://www.twitch.tv/lichessdotorg" + }, + "youTube": { + "channel": "https://www.youtube.com/c/LichessDotOrg" + } + } + }, + "followable": { + "type": "boolean", + "example": true, + "description": "only appears if the request is [authenticated with OAuth2](#section/Introduction/Authentication)" + }, + "following": { + "type": "boolean", + "example": false, + "description": "only appears if the request is [authenticated with OAuth2](#section/Introduction/Authentication)" + }, + "blocking": { + "type": "boolean", + "example": false, + "description": "only appears if the request is [authenticated with OAuth2](#section/Introduction/Authentication)" + }, + "followsYou": { + "type": "boolean", + "example": false, + "description": "only appears if the request is [authenticated with OAuth2](#section/Introduction/Authentication)" + } + } + } + ] + }, + "RatingHistory": { + "example": [ + { + "name": "Bullet", + "points": [ + [ + 2011, + 0, + 8, + 1472 + ], + [ + 2011, + 0, + 9, + 1332 + ], + [ + 2011, + 8, + 12, + 1314 + ] + ] + }, + { + "name": "Blitz", + "points": [ + [ + 2011, + 7, + 29, + 1332 + ] + ] + } + ] + }, + "PerfType": { + "type": "string", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "correspondence", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck" + ] + }, + "PerfStat": { + "example": { + "perf": { + "glicko": { + "rating": 1672.42, + "deviation": 45.13, + "provisional": false + }, + "nb": 5692, + "progress": -27 + }, + "rank": 98121, + "percentile": 69.7, + "stat": { + "perfType": { + "key": "bullet", + "name": "Bullet" + }, + "highest": { + "int": 1902, + "at": "2021-05-31T08:58:53.701Z", + "gameId": "YEDqtwig" + }, + "lowest": { + "int": 1417, + "at": "2016-06-28T13:54:39.656Z", + "gameId": "rNM4J1GJ" + }, + "bestWins": { + "results": [ + { + "opInt": 2238, + "opId": { + "id": "hyperdragon84", + "name": "HyperDragon84" + }, + "at": "2019-06-19T17:09:05.187Z", + "gameId": "DGB53z9w" + }, + { + "opInt": 2089, + "opId": { + "id": "osipov", + "name": "osipov" + }, + "at": "2017-06-18T09:46:05.016Z", + "gameId": "gurRhuMi" + }, + { + "opInt": 2071, + "opId": { + "id": "spark50", + "name": "Spark50" + }, + "at": "2020-07-04T08:36:12.948Z", + "gameId": "a93Dk1mv" + }, + { + "opInt": 2045, + "opId": { + "id": "yasha43", + "name": "Yasha43" + }, + "at": "2021-05-17T14:01:41.098Z", + "gameId": "j3jZnGTr" + }, + { + "opInt": 2034, + "opId": { + "id": "midedu", + "name": "midedu" + }, + "at": "2020-06-27T17:32:47.001Z", + "gameId": "OiaMVLQ8" + } + ] + }, + "worstLosses": { + "results": [ + { + "opInt": 1186, + "opId": { + "id": "happy0", + "name": "Happy0" + }, + "at": "2016-07-07T19:48:29.077Z", + "gameId": "Q01bbiN4" + }, + { + "opInt": 1197, + "opId": { + "id": "kazmankiller86", + "name": "KazmanKiller86" + }, + "at": "2016-10-16T14:21:37.748Z", + "gameId": "Aivqh9Sp" + }, + { + "opInt": 1201, + "opId": { + "id": "artem555", + "name": "artem555" + }, + "at": "2016-08-28T16:21:30.923Z", + "gameId": "tiRAbhnX" + }, + { + "opInt": 1265, + "opId": { + "id": "arcenuu", + "name": "Arcenuu" + }, + "at": "2016-12-24T14:28:03.866Z", + "gameId": "A68wUOoh" + }, + { + "opInt": 1283, + "opId": { + "id": "amritalib76", + "name": "Amritalib76" + }, + "at": "2018-06-26T09:55:39.354Z", + "gameId": "sbNVikmo" + } + ] + }, + "count": { + "all": 5858, + "rated": 5688, + "win": 2789, + "loss": 2806, + "draw": 263, + "tour": 654, + "berserk": 1, + "opAvg": 1671.44, + "seconds": 784886, + "disconnects": 0 + }, + "resultStreak": { + "win": { + "cur": { + "v": 0 + }, + "max": { + "v": 11, + "from": { + "at": "2021-06-14T15:38:50.681Z", + "gameId": "wTX2IExo" + }, + "to": { + "at": "2021-06-15T18:41:46.970Z", + "gameId": "1z4rrjgw" + } + } + }, + "loss": { + "cur": { + "v": 3, + "from": { + "at": "2021-06-29T17:53:23.642Z", + "gameId": "pfcnjgik" + }, + "to": { + "at": "2021-06-29T18:04:48.358Z", + "gameId": "6sPaGL8T" + } + }, + "max": { + "v": 14, + "from": { + "at": "2018-06-11T14:43:39.296Z", + "gameId": "1fc9dqun" + }, + "to": { + "at": "2018-06-11T15:10:30.908Z", + "gameId": "Nzy6UgwY" + } + } + } + }, + "playStreak": { + "nb": { + "cur": { + "v": 0 + }, + "max": { + "v": 118, + "from": { + "at": "2018-06-11T10:32:21.248Z", + "gameId": "UAsNnJbN" + }, + "to": { + "at": "2018-06-11T15:13:01.193Z", + "gameId": "T7fHRaFG" + } + } + }, + "time": { + "cur": { + "v": 0 + }, + "max": { + "v": 12683, + "from": { + "at": "2018-06-12T14:11:14.021Z", + "gameId": "IrZCAW58" + }, + "to": { + "at": "2018-06-12T18:02:57.010Z", + "gameId": "RNF1mQ68" + } + } + }, + "lastDate": "2021-06-29T18:04:48.358Z" + } + } + } + }, + "PuzzleAndGame": { + "example": { + "game": { + "clock": "10+0", + "id": "VpVdGbna", + "perf": { + "key": "rapid", + "name": "Rapid" + }, + "pgn": "d4 Nf6 Nf3 g6 Nc3 d6 e4 c5 Be3 cxd4 Bxd4 Nc6 Be3 Qa5 Bd2 Bg7 Be2 O-O O-O Qb6 Rb1 Bg4 h3 Bxf3 Bxf3 Nd4 Be3 Nxf3+ Qxf3 Qc6 Bd4 a6 Bxf6 Bxf6 Nd5 Qxc2 Nxf6+ exf6 Qxf6 Qxe4 Qxd6 Rad8 Qb6 Rfe8 Rfe1 Qxe1+ Rxe1 Rxe1+ Kh2 Rd2 Kg3 Ree2 Qxb7 Rxb2 Qxa6 Rxa2 Qc8+ Kg7 Qc3+ Kg8 Qc5 Rxf2 Qc8+ Kg7 Qc3+ Kh6 Qe3+ Kg7 Qe5+ Kf8 Qh8+ Ke7 Qe5+ Kf8 Qb8+ Kg7 Qe5+ f6 Qe7+ Kh6 Qf8+ Kg5 h4+ Kh5 Qc5+ f5 Qc1 Rxg2+ Kh3 Rh2+ Kg3 Rag2+ Kf3 Rg4 Qd1 Rhxh4 Kf2 Rh2+ Kf3 Rh3+ Ke2 Rg2+ Kf1+ Rg4 Kf2 g5 Qd8 h6 Qe8+ Kh4 Kf1 h5 Qe1+ Rhg3 Qe5 f4 Qe1 f3 Kf2 Rf4 Qh1+ Rh3 Qe1 g4", + "players": [ + { + "color": "white", + "name": "borska (2013)", + "userId": "borska" + }, + { + "color": "black", + "name": "Xxn00bkillar69xX (1990)", + "userId": "xxn00bkillar69xx" + } + ], + "rated": true + }, + "puzzle": { + "id": "K69di", + "initialPly": 123, + "plays": 1970, + "rating": 2022, + "solution": [ + "e1e7", + "f4f6", + "e7f6" + ], + "themes": [ + "short", + "queenRookEndgame", + "endgame", + "mateIn2" + ] + } + } + }, + "PuzzleRoundJson": { + "type": "object", + "properties": { + "date": { + "type": "number", + "example": 1514505150384 + }, + "win": { + "type": "boolean", + "example": true + }, + "puzzle": { + "type": "object", + "example": { + "id": "K69di", + "fen": "6k1/6b1/8/4p1N1/7Q/2P2pP1/1Pq2P1K/8 w - - 14 49", + "plays": 1970, + "rating": 2022, + "solution": [ + "e1e7", + "f4f6", + "e7f6" + ], + "themes": [ + "short", + "queenRookEndgame", + "endgame", + "mateIn2" + ] + } + } + } + }, + "PuzzleDashboardJson": { + "example": { + "days": 30, + "global": { + "firstWins": 276, + "nb": 501, + "performance": 1570, + "puzzleRatingAvg": 1523, + "replayWins": 2 + }, + "themes": { + "advancedPawn": { + "results": { + "firstWins": 19, + "nb": 39, + "performance": 1438, + "puzzleRatingAvg": 1476, + "replayWins": 1 + }, + "theme": "Advanced pawn" + }, + "anastasiaMate": { + "results": { + "firstWins": 5, + "nb": 6, + "performance": 1720, + "puzzleRatingAvg": 1387, + "replayWins": 0 + }, + "theme": "Anastasia's mate" + } + } + } + }, + "StormDashboardJson": { + "example": { + "high": { + "allTime": 11, + "day": 0, + "month": 7, + "week": 0 + }, + "days": [ + { + "_id": "2021/1/28", + "combo": 8, + "errors": 1, + "highest": 1084, + "moves": 9, + "runs": 26, + "score": 4, + "time": 175 + }, + { + "_id": "2021/1/27", + "combo": 14, + "errors": 1, + "highest": 1095, + "moves": 15, + "runs": 15, + "score": 7, + "time": 23 + }, + { + "_id": "2021/1/22", + "combo": 14, + "errors": 1, + "highest": 1095, + "moves": 15, + "runs": 15, + "score": 3, + "time": 23 + } + ] + } + }, + "PuzzleRaceJson": { + "example": { + "id": "Kj1t0", + "url": "https://lichess.org/racer/Kj1t0" + } + }, + "UserPreferences": { + "type": "object", + "properties": { + "dark": { + "type": "boolean", + "example": true + }, + "transp": { + "type": "boolean", + "example": false + }, + "bgImg": { + "type": "string", + "format": "uri" + }, + "is3d": { + "type": "boolean", + "example": false + }, + "theme": { + "type": "string", + "enum": [ + "blue", + "blue2", + "blue3", + "blue-marble", + "canvas", + "wood", + "wood2", + "wood3", + "wood4", + "maple", + "maple2", + "brown", + "leather", + "green", + "marble", + "green-plastic", + "grey", + "metal", + "olive", + "newspaper", + "purple", + "purple-diag", + "pink", + "ic" + ] + }, + "pieceSet": { + "type": "string", + "enum": [ + "cburnett", + "merida", + "alpha", + "pirouetti", + "chessnut", + "chess7", + "reillycraig", + "companion", + "riohacha", + "kosal", + "leipzig", + "fantasy", + "spatial", + "california", + "pixel", + "maestro", + "fresca", + "cardinal", + "gioco", + "tatiana", + "staunty", + "governor", + "dubrovny", + "icpieces", + "shapes", + "letter" + ] + }, + "theme3d": { + "type": "string", + "enum": [ + "Black-White-Aluminium", + "Brushed-Aluminium", + "China-Blue", + "China-Green", + "China-Grey", + "China-Scarlet", + "Classic-Blue", + "Gold-Silver", + "Light-Wood", + "Power-Coated", + "Rosewood", + "Marble", + "Wax", + "Jade", + "Woodi" + ] + }, + "pieceSet3d": { + "type": "string", + "enum": [ + "Basic", + "Wood", + "Metal", + "RedVBlue", + "ModernJade", + "ModernWood", + "Glass", + "Trimmed", + "Experimental", + "Staunton", + "CubesAndPi" + ] + }, + "soundSet": { + "type": "string", + "enum": [ + "silent", + "standard", + "piano", + "nes", + "sfx", + "futuristic", + "robot", + "music", + "speech" + ] + }, + "blindfold": { + "type": "integer", + "example": 0 + }, + "autoQueen": { + "type": "integer", + "example": 2 + }, + "autoThreefold": { + "type": "integer", + "example": 2 + }, + "takeback": { + "type": "integer", + "example": 3 + }, + "moretime": { + "type": "integer", + "example": 3 + }, + "clockTenths": { + "type": "integer", + "example": 1 + }, + "clockBar": { + "type": "boolean", + "example": true + }, + "clockSound": { + "type": "boolean", + "example": true + }, + "premove": { + "type": "boolean", + "example": true + }, + "animation": { + "type": "integer", + "example": 2 + }, + "captured": { + "type": "boolean", + "example": true + }, + "follow": { + "type": "boolean", + "example": true + }, + "highlight": { + "type": "boolean", + "example": true + }, + "destination": { + "type": "boolean", + "example": true + }, + "coords": { + "type": "integer", + "example": 2 + }, + "replay": { + "type": "integer", + "example": 2 + }, + "challenge": { + "type": "integer", + "example": 4 + }, + "message": { + "type": "integer", + "example": 3 + }, + "coordColor": { + "type": "integer", + "example": 2 + }, + "submitMove": { + "type": "integer", + "example": 4 + }, + "confirmResign": { + "type": "integer", + "example": 1 + }, + "insightShare": { + "type": "integer", + "example": 1 + }, + "keyboardMove": { + "type": "integer", + "example": 0 + }, + "zen": { + "type": "integer", + "example": 0 + }, + "moveEvent": { + "type": "integer", + "example": 2 + }, + "rookCastle": { + "type": "integer", + "example": 1 + } + } + }, + "Ok": { + "properties": { + "ok": { + "type": "boolean" + } + }, + "example": { + "ok": true + } + }, + "Timeline": { + "type": "object", + "properties": { + "entries": { + "type": "array" + }, + "users": { + "type": "object" + } + }, + "example": { + "entries": [ + { + "type": "follow", + "data": { + "u1": "neio", + "u2": "chess-network" + }, + "date": 1644232201429 + }, + { + "type": "team-join", + "data": { + "userId": "neio", + "teamId": "coders" + }, + "date": 1644232201429 + }, + { + "type": "team-create", + "data": { + "userId": "neio", + "teamId": "coders" + }, + "date": 1644232201429 + }, + { + "type": "forum-post", + "data": { + "userId": "neio", + "topicId": "AAAAAAAN", + "topicName": "World's Tallest LEGO Tower Completed in City Square", + "postId": "AAAAAAAL" + }, + "date": 1644232201429 + }, + { + "type": "ublog-post", + "data": { + "userId": "neio", + "id": "og5pkt1c", + "slug": "gotta-go-fast", + "title": "Gotta Go Fast" + }, + "date": 1644232201429 + }, + { + "type": "tour-join", + "data": { + "userId": "chess-network", + "tourId": "Z24oxqgU", + "tourName": "Daily Blitz Arena" + }, + "date": 1644232201429 + }, + { + "type": "game-end", + "data": { + "fullId": "iGkAXUdEfLZC", + "perf": "correspondence", + "opponent": "chess-network", + "win": false + }, + "date": 1644232201429 + }, + { + "type": "simul-create", + "data": { + "userId": "neio", + "simulId": "m3c0Wvu3", + "simulName": "RCA 1st Jan simul" + }, + "date": 1644232201429 + }, + { + "type": "simul-join", + "data": { + "userId": "chess-network", + "simulId": "m3c0Wvu3", + "simulName": "RCA 1st Jan simul" + }, + "date": 1644232201429 + }, + { + "type": "study-like", + "data": { + "userId": "neio", + "studyId": "ma5AvZ7o", + "studyName": "Free wins | Danish Gambit" + }, + "date": 1644232201429 + }, + { + "type": "plan-start", + "data": { + "userId": "chess-network" + }, + "date": 1644232201429 + }, + { + "type": "plan-renew", + "data": { + "userId": "chess-network", + "months": 64 + }, + "date": 1644232201429 + }, + { + "type": "blog-post", + "data": { + "id": "ZUviXRIAACYAVtMm", + "slug": "lichess-development-made-easy-with-gitpod", + "title": "Lichess Development Made Easy With Gitpod" + }, + "date": 1644232201429 + }, + { + "type": "ublog-post-like", + "data": { + "userId": "neio", + "id": "ZUviXRIAACYAVtMm", + "title": "Lichess Development Made Easy With Gitpod" + }, + "date": 1644232201429 + }, + { + "type": "stream-start", + "data": { + "userId": "chess-network", + "title": "Streamers Battle December !team | lichess.org" + }, + "date": 1644232201429 + } + ], + "users": { + "neio": { + "id": "neio", + "name": "Neio", + "title": "NM" + }, + "chess-network": { + "id": "chess-network", + "name": "Chess-Network", + "title": "NM", + "patron": true + } + } + } + }, + "GamePgn": { + "example": "[Event \"Rated Blitz game\"]\n[Site \"https://lichess.org/fY44h4OY\"]\n[Date \"2018.03.29\"]\n[Round \"-\"]\n[White \"pveldman\"]\n[Black \"thibault\"]\n[Result \"1-0\"]\n[UTCDate \"2018.03.29\"]\n[UTCTime \"01:38:15\"]\n[WhiteElo \"1610\"]\n[BlackElo \"1601\"]\n[WhiteRatingDiff \"+10\"]\n[BlackRatingDiff \"-10\"]\n[Variant \"Standard\"]\n[TimeControl \"180+0\"]\n[ECO \"C62\"]\n[Opening \"Ruy Lopez: Steinitz Defense\"]\n[Termination \"Normal\"]\n[Event \"U1700 SuperBlitz Arena\"]\n\n1. e4 { [%clk 0:03:00] } e5 { [%clk 0:03:00] } 2. Nf3 { [%clk 0:02:59] } Nc6 { [%clk 0:02:58] } 3. Bb5 { [%clk 0:02:57] } d6 { [%clk 0:02:55] } 4. h3 { [%clk 0:02:54] } Nf6 { [%clk 0:02:52] } 5. Bxc6+ { [%clk 0:02:52] } bxc6 { [%clk 0:02:49] } 6. d3 { [%clk 0:02:51] } Be7 { [%clk 0:02:46] } 7. O-O { [%clk 0:02:47] } O-O { [%clk 0:02:45] } 8. b3 { [%clk 0:02:45] } d5 { [%clk 0:02:45] } 9. exd5 { [%clk 0:02:33] } cxd5 { [%clk 0:02:40] } 10. Nxe5 { [%clk 0:02:31] } Qd6 { [%clk 0:02:38] } 1-0\n" + }, + "VariantKey": { + "type": "string", + "enum": [ + "standard", + "chess960", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingOfTheHill", + "racingKings", + "threeCheck", + "fromPosition" + ], + "example": "standard", + "default": "standard" + }, + "Speed": { + "type": "string", + "enum": [ + "ultraBullet", + "bullet", + "blitz", + "rapid", + "classical", + "correspondence" + ] + }, + "GameStatus": { + "type": "string", + "description": "Game status code. https://github.com/lichess-org/scalachess/blob/0a7d6f2c63b1ca06cd3c958ed3264e738af5c5f6/src/main/scala/Status.scala#L16-L28", + "enum": [ + "created", + "started", + "aborted", + "mate", + "resign", + "stalemate", + "timeout", + "draw", + "outoftime", + "cheat", + "noStart", + "unknownFinish", + "variantEnd" + ] + }, + "LightUser": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "chess-network" + }, + "name": { + "type": "string", + "example": "Chess-Network" + }, + "title": { + "$ref": "#/components/schemas/Title" + }, + "patron": { + "type": "boolean", + "example": true + } + }, + "required": [ + "id", + "name" + ] + }, + "GameUser": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/LightUser" + }, + "rating": { + "type": "number" + }, + "ratingDiff": { + "type": "number" + }, + "name": { + "type": "string" + }, + "provisional": { + "type": "boolean" + }, + "aiLevel": { + "type": "number" + }, + "analysis": { + "type": "object", + "properties": { + "inaccuracy": { + "type": "number" + }, + "mistake": { + "type": "number" + }, + "blunder": { + "type": "number" + }, + "acpl": { + "type": "number" + } + }, + "required": [ + "inaccuracy", + "mistake", + "blunder", + "acpl" + ] + }, + "team": { + "type": "string" + } + } + }, + "GameJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "rated": { + "type": "boolean" + }, + "variant": { + "$ref": "#/components/schemas/VariantKey" + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "perf": { + "type": "string" + }, + "createdAt": { + "type": "number", + "format": "int64" + }, + "lastMoveAt": { + "type": "number", + "format": "int64" + }, + "status": { + "$ref": "#/components/schemas/GameStatus" + }, + "players": { + "type": "object", + "properties": { + "white": { + "$ref": "#/components/schemas/GameUser" + }, + "black": { + "$ref": "#/components/schemas/GameUser" + } + } + }, + "initialFen": { + "type": "string" + }, + "winner": { + "type": "string", + "enum": [ + "white", + "black" + ] + }, + "opening": { + "type": "object", + "properties": { + "eco": { + "type": "string" + }, + "name": { + "type": "string" + }, + "ply": { + "type": "number" + } + } + }, + "moves": { + "type": "string" + }, + "pgn": { + "type": "string" + }, + "daysPerTurn": { + "type": "number" + }, + "analysis": { + "type": "array", + "items": { + "type": "object", + "properties": { + "eval": { + "type": "number", + "description": "Evaluation in centipawns" + }, + "mate": { + "type": "number", + "description": "Number of moves until forced mate" + }, + "best": { + "type": "string", + "example": "c2c3", + "description": "Best move in UCI notation (only if played move was inaccurate)" + }, + "variation": { + "type": "string", + "example": "c3 Nc6 d4 Qb6 Be2 Nge7 Na3 cxd4 cxd4 Nf5", + "description": "Best variation in SAN notation (only if played move was inaccurate)" + }, + "judgment": { + "type": "object", + "description": "Judgment annotation (only if played move was inaccurate)", + "properties": { + "name": { + "type": "string", + "enum": [ + "Inaccuracy", + "Mistake", + "Blunder" + ] + }, + "comment": { + "type": "string", + "example": "Blunder. Nxg6 was best." + } + } + } + }, + "required": [] + } + }, + "tournament": { + "type": "string" + }, + "swiss": { + "type": "string" + }, + "clock": { + "type": "object", + "properties": { + "initial": { + "type": "number" + }, + "increment": { + "type": "number" + }, + "totalTime": { + "type": "number" + } + } + }, + "division": { + "type": "object", + "properties": { + "middle": { + "type": "number", + "description": "Ply at which the middlegame begins" + }, + "end": { + "type": "number", + "description": "Ply at which the endgame begins" + } + }, + "required": [] + } + }, + "required": [ + "id", + "rated", + "variant", + "speed", + "perf", + "createdAt", + "lastMoveAt", + "status", + "players" + ], + "example": { + "id": "q7ZvsdUF", + "rated": true, + "variant": "standard", + "speed": "blitz", + "perf": "blitz", + "createdAt": 1514505150384, + "lastMoveAt": 1514505592843, + "status": "draw", + "players": { + "white": { + "user": { + "name": "Lance5500", + "title": "LM", + "patron": true, + "id": "lance5500" + }, + "rating": 2389, + "ratingDiff": 4 + }, + "black": { + "user": { + "name": "TryingHard87", + "id": "tryinghard87" + }, + "rating": 2498, + "ratingDiff": -4 + } + }, + "opening": { + "eco": "D31", + "name": "Semi-Slav Defense: Marshall Gambit", + "ply": 7 + }, + "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": { + "initial": 300, + "increment": 3, + "totalTime": 420 + } + } + }, + "GameStream": { + "example": [ + { + "id": "A5fcMO3k", + "rated": true, + "variant": "standard", + "speed": "bullet", + "perf": "bullet", + "createdAt": 1525789431889, + "status": 20, + "statusName": "started", + "clock": { + "initial": 60, + "increment": 0, + "totalTime": 60 + }, + "players": { + "white": { + "userId": "kastorcito", + "rating": 2617 + }, + "black": { + "userId": "er_or", + "rating": 2288 + } + } + } + ] + }, + "MoveStream": { + "example": [ + { + "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", + "players": { + "white": { + "user": { + "name": "ARM-777777", + "title": "GM", + "id": "arm-777777" + }, + "rating": 3120 + }, + "black": { + "user": { + "name": "Flash_Marafon", + "id": "flash_marafon" + }, + "rating": 3015 + } + } + }, + { + "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkbnr/pppppppp/8/8/8/4P3/PPPP1PPP/RNBQKBNR b", + "lm": "e2e3", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkb1r/pppppppp/7n/8/8/4P3/PPPP1PPP/RNBQKBNR w", + "lm": "g8h6", + "wc": 180, + "bc": 180 + }, + { + "fen": "rnbqkb1r/pppppppp/7n/8/8/1P2P3/P1PP1PPP/RNBQKBNR b", + "lm": "b2b3", + "wc": 177, + "bc": 180 + }, + { + "fen": "rnbqkb1r/1ppppppp/p6n/8/8/1P2P3/P1PP1PPP/RNBQKBNR w", + "lm": "a7a6", + "wc": 177, + "bc": 177 + } + ] + }, + "TvFeed": { + "type": "object", + "properties": { + "t": { + "type": "string" + }, + "d": { + "type": "object" + } + } + }, + "Clock": { + "type": "object", + "properties": { + "limit": { + "type": "integer" + }, + "increment": { + "type": "integer" + } + } + }, + "Variant": { + "type": "object", + "properties": { + "key": { + "$ref": "#/components/schemas/VariantKey" + }, + "name": { + "type": "string" + }, + "short": { + "type": "string" + } + } + }, + "ArenaStatus": { + "type": "integer", + "description": "10: created, 20: started, 30: finished\n", + "enum": [ + 10, + 20, + 30 + ], + "example": 30 + }, + "ArenaPerf": { + "type": "object", + "properties": { + "key": { + "type": "string", + "example": "blitz" + }, + "name": { + "type": "string", + "example": "Blitz" + }, + "position": { + "type": "integer", + "example": 1 + }, + "icon": { + "type": "string", + "example": ")" + } + } + }, + "ArenaRatingObj": { + "type": "object", + "properties": { + "perf": { + "$ref": "#/components/schemas/PerfType" + }, + "rating": { + "type": "integer", + "example": 1700 + } + } + }, + "ArenaPosition": { + "oneOf": [ + { + "type": "object", + "title": "Thematic", + "properties": { + "eco": { + "type": "string", + "example": "C41" + }, + "name": { + "type": "string", + "example": "Philidor Defense" + }, + "fen": { + "type": "string", + "example": "rnbqkbnr/ppp2ppp/3p4/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq -" + }, + "url": { + "type": "string", + "example": "https://lichess.org/opening/Philidor_Defense" + } + } + }, + { + "type": "object", + "title": "Custom position", + "properties": { + "name": { + "type": "string", + "const": "Custom position" + }, + "fen": { + "type": "string", + "example": "rnbq1bnr/ppppkppp/8/4p3/4P3/8/PPPPKPPP/RNBQ1BNR w - - 2 3" + } + } + } + ] + }, + "ArenaTournament": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "QITRjufu" + }, + "createdBy": { + "type": "string", + "example": "lichess" + }, + "system": { + "type": "string", + "const": "arena" + }, + "minutes": { + "type": "integer", + "example": 57 + }, + "clock": { + "$ref": "#/components/schemas/Clock" + }, + "rated": { + "type": "boolean", + "example": true + }, + "fullName": { + "type": "string", + "example": "U1700 SuperBlitz Arena" + }, + "nbPlayers": { + "type": "integer", + "example": 154 + }, + "variant": { + "$ref": "#/components/schemas/Variant" + }, + "startsAt": { + "type": "integer", + "example": 1522803600000 + }, + "finishesAt": { + "type": "integer", + "example": 1522807200000 + }, + "status": { + "$ref": "#/components/schemas/ArenaStatus" + }, + "perf": { + "$ref": "#/components/schemas/ArenaPerf" + }, + "secondsToStart": { + "type": "integer", + "example": 576 + }, + "hasMaxRating": { + "type": "boolean", + "example": true + }, + "maxRating": { + "$ref": "#/components/schemas/ArenaRatingObj" + }, + "minRating": { + "$ref": "#/components/schemas/ArenaRatingObj" + }, + "minRatedGames": { + "type": "object", + "properties": { + "nb": { + "type": "integer", + "example": 20 + }, + "perf": { + "$ref": "#/components/schemas/PerfType", + "example": "blitz" + } + } + }, + "onlyTitled": { + "type": "boolean", + "example": false + }, + "teamMember": { + "type": "string", + "example": "coders" + }, + "private": { + "type": "boolean", + "example": true + }, + "position": { + "$ref": "#/components/schemas/ArenaPosition" + }, + "schedule": { + "type": "object", + "properties": { + "freq": { + "type": "string", + "example": "hourly" + }, + "speed": { + "type": "string", + "example": "superblitz" + } + } + }, + "teamBattle": { + "type": "object", + "properties": { + "teams": { + "type": "array", + "items": { + "type": "string", + "example": "coders" + } + }, + "nbLeaders": { + "type": "integer", + "example": 3 + } + } + }, + "winner": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "lichess" + }, + "name": { + "type": "string", + "example": "lichess" + }, + "title": { + "$ref": "#/components/schemas/Title" + } + } + } + } + }, + "ArenaTournaments": { + "type": "object", + "properties": { + "created": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + }, + "started": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + }, + "finished": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArenaTournament" + } + } + } + }, + "FromPositionFEN": { + "type": "string", + "description": "Custom initial position (in FEN). Variant must be standard, fromPosition, or chess960 (if a valid 960 starting position), and the game cannot be rated.", + "default": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + "ArenaTournamentVariantIsKey": { + "example": { + "id": "QITRjufu", + "fullName": "U1700 SuperBlitz Arena", + "rated": true, + "clock": { + "increment": 0, + "limit": 180 + }, + "minutes": 57, + "createdBy": "lichess", + "system": "arena", + "secondsToStart": 0, + "secondsToFinish": 36000, + "isFinished": true, + "isRecentlyFinished": true, + "pairingsClosed": true, + "startsAt": 1522803600000, + "nbPlayers": 154, + "perf": { + "icon": ")", + "key": "blitz", + "name": "Blitz", + "position": 1 + }, + "schedule": { + "freq": "hourly", + "speed": "superblitz" + }, + "variant": "standard", + "duels": [ + { + "id": "0MM6q4tQ", + "p": [ + { + "n": "player1", + "r": 1500, + "k": 3 + }, + { + "n": "player2", + "r": 1500, + "k": 3 + } + ] + } + ], + "standings": { + "page": 1, + "players": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "sheet": { + "scores": [ + { + "0": 2, + "1": 2 + }, + { + "0": 4, + "1": 3 + }, + 0 + ], + "total": 6, + "fire": true + } + } + ] + }, + "featured": { + "id": "khe72Fer", + "fen": "rn1qkb1r/pQ3ppp/2b2n2/8/5P2/4P3/PP4PP/RNB1KBNR", + "color": "black", + "lastMove": "d7c6", + "white": { + "rank": 2, + "name": "player1", + "rating": 1360 + }, + "black": { + "rank": 5, + "name": "player2", + "rating": 1431 + } + }, + "podium": [ + { + "name": "player1", + "rank": 1, + "rating": 1500, + "score": 3, + "sheet": { + "scores": [ + { + "0": 2, + "1": 2 + }, + { + "0": 4, + "1": 3 + }, + 0 + ], + "total": 6, + "fire": true + }, + "nb": { + "game": 3, + "beserk": 0, + "win": 2 + }, + "performance": 1787 + } + ], + "stats": { + "games": 454, + "moves": 27542, + "whiteWins": 236, + "blackWins": 207, + "draws": 11, + "berserks": 0, + "averageRating": 1320 + } + } + }, + "Error": { + "properties": { + "error": { + "type": "string", + "description": "The cause of the error." + } + }, + "example": { + "error": "This request is invalid because [...]" + } + }, + "SwissTournament": { + "example": { + "rated": true, + "clock": { + "increment": 0, + "limit": 300 + }, + "createdBy": "thibault", + "id": "ZmKWCOye", + "name": "Wang", + "nbOngoing": 0, + "nbPlayers": 0, + "nbRounds": 2, + "nextRound": { + "at": "2020-05-11T12:23:18.233-06:00", + "in": 600 + }, + "round": 0, + "startsAt": "2020-05-11T12:23:18.233-06:00", + "status": "created", + "variant": "standard", + "isRecentlyFinished": false, + "password": true, + "stats": { + "absences": 1608, + "averageRating": 1588, + "blackWins": 42541, + "byes": 12, + "draws": 0, + "games": 42689, + "whiteWins": 42837 + } + } + }, + "SwissUnauthorisedEdit": { + "properties": { + "error": { + "type": "string" + } + }, + "example": { + "error": "This user cannot edit this swiss" + } + }, + "StudyPgn": { + "example": "[Event \"All about the Sicilian Defense: Dragon Variation\"]\n[Site \"https://lichess.org/study/8c8bmUfy/qwnXMwVC\"]\n[Result \"*\"]\n[UTCDate \"2017.06.25\"]\n[UTCTime \"10:12:04\"]\n[Variant \"Standard\"]\n[ECO \"B76\"]\n[Opening \"Sicilian Defense: Dragon Variation, Yugoslav Attack, Panov Variation\"]\n[Annotator \"https://lichess.org/@/Francesco_Super\"]\n\n{ This chapter will go over the Dragon Variation, a very common variation used by Black and it is the most aggressive variation in the Sicilian defense. }\n1. e4 c5 2. Nf3 { Simple developing move to control the d4 square } { [%csl Gd4,Gc5][%cal Gf3d4,Gc5d4] } 2... d6 { [%cal Gd6e5] } (2... e6 3. d4 cxd4 4. Nxd4 Nf6 5. e5 (5. Nc3 { [%cal Ge4e5] }) 5... Qa5+) 3. d4 { Whites want the exchange of pawns } { [%cal Gc5d4] } 3... cxd4 { [%cal Gf3d4] } 4. Nxd4 { Whites are now ahead in development but blacks still have the two central pawns whereas whites only one. } { [%csl Ge7,Gd6,Ge4] } 4... Nf6 { Blacks are now developing their knight and threatening the e4 pawn } { [%csl Ge4][%cal Gf6e4] } 5. Nc3 { The e4 pawn is now protected by the c3 knight } { [%csl Ge4,Bc3][%cal Rf6e4,Bc3e4] } 5... g6 { This is the DRAGON VARIATION. g6 allows the dark-squared bishop to develop and move to g7, controlling the long dark-squared diagonal } { [%csl Gd4] } 6. Be3 { [%cal Gd1d2,Gf2f3,Ge1c1,Gg2g4,Gh2h4,Gg4g5] } (6. Be2 Bg7 7. O-O Nc6 8. Be3 { [%cal Ge3d4] } (8. f3 Nxe4 { [%cal Gg7d4,Gc6d4] } 9. Nxc6 Qb6+ { [%cal Gb6c6,Gb6g1] } 10. Kh1 Nxc3 { [%cal Gc3d1,Gc3e2] } 11. bxc3 bxc6 { [%cal Gc8a6] }) 8... O-O 9. Nb3 a6 { [%cal Gb7b5,Gb5b4,Ge2c4] }) 6... Bg7 (6... Ng4 { [%cal Gg4e3] } 7. Bb5+ { [%cal Gb5e8,Gb8d7,Gc8d7,Gd1g4] } 7... Nc6 8. Nxc6 bxc6 9. Bxc6+ { [%cal Gc6a8] }) 7. f3 { The key opening moves for White, who attempt to castle queenside , whereas f3 strengthens the pawn structure, connecting e4 to the h2 and g2, while White also plan pushing to g4 and possibly h4. } { [%csl Bf3,Be3][%cal Rg2g4,Rh2h4,Rg4g5] } 7... O-O (7... h5 { Is operating against g4. }) 8. Qd2 { [%csl Gh6,Gg7][%cal Ge1c1,Ga1d1,Re3h6,Rd2h6] } 8... Nc6 { [%csl Gc6,Gh6][%cal Gb8c6,Ge1c1,Ga7a6,Ge3h6] } 9. g4 (9. Bh6 { [%cal Ge3d4] } 9... Bxh6 10. Qxh6 Nxd4) 9... Be6 10. Nxe6 fxe6 { [%cal Gf8f1] } 11. O-O-O Ne5 12. Be2 { [%csl Gf3][%cal Re5f3,Bd1h1,Bg1d1] } 12... Qc7 { [%csl Gc4][%cal Ge5c4,Gc4e3,Gc4d2,Bf8c8,Yc7c3] } 13. h4 Nc4 *\n" + }, + "StudyImportPgnChapters": { + "example": { + "chapters": [ + { + "id": "WTvnkWAL", + "name": "Game 2" + } + ] + } + }, + "StudyMetadata": { + "example": { + "id": "WTvnkWAL", + "name": "Guess the move", + "createdAt": 1463756350225, + "updatedAt": 1469965025205 + } + }, + "BroadcastTour": { + "example": { + "tour": { + "id": "QYiOYnl1", + "name": "New in Chess Classic | Finals", + "slug": "new-in-chess-classic--finals", + "description": "Match for 1st 2nd and 3rd place.", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/phgcXuBl", + "createdAt": 1525789431889 + }, + "rounds": [ + { + "id": "BueO56UJ", + "name": "Finals Day 1", + "slug": "finals-day-1", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-1/BueO56UJ", + "createdAt": 1525789431889 + }, + { + "id": "yeGGfkfY", + "name": "Finals Day 2", + "slug": "finals-day-2", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-2/yeGGfkfY", + "createdAt": 1525789431889 + } + ] + } + }, + "BroadcastForm": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the broadcast tournament. Length must be between 3 and 80 characters.\n\nExample: `Sinquefield Cup`\n" + }, + "description": { + "type": "string", + "description": "Short description of the broadcast tournament. Length must be between 3 and 400 characters.\n\nExample: `An 11 round classical tournament featuring the 9 highest rated players in the world. Including Carlsen, Caruana, Ding, Aronian, Nakamura and more.`\n" + }, + "autoLeaderboard": { + "type": "boolean", + "description": "Compute and display a simple leaderboard based on game results" + }, + "markdown": { + "type": "string", + "description": "Optional long description of the broadcast. Markdown is supported. Length must be less than 20,000 characters." + }, + "tier": { + "type": "integer", + "description": "Optional, for Lichess admins only, use to feature on /broadcast.\n\n* `3` for normal\n* `4` for high\n* `5` for best\n" + }, + "players": { + "description": "Optional replace player names, ratings and titles.\n\nOne line per player, formatted as such:\n\n`player name = FIDE ID`\n\nExample:\n\n`Magnus Carlsen = 1503014`\n\nPlayer names ignore case and punctuation, and match all possible combinations of 2 words:\n\"Jorge Rick Vito\" will match \"Jorge Rick\", \"jorge vito\", \"Rick, Vito\", etc. \n\nAlternatively, you may set tags manually, like so:\n\n`player name / rating / title / new name`\n\nAll values are optional. Example:\n\n`Magnus Carlsen / 2863 / GM` \n`YouGotLittUp / 1890 / / Louis Litt`\n" + } + }, + "required": [ + "name", + "description", + "autoLeaderboard" + ] + }, + "BroadcastLeaderboardEntry": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "Hernandez Riera, Jose" + }, + "score": { + "type": "number", + "example": 2.5 + }, + "played": { + "type": "integer", + "example": 7 + }, + "rating": { + "type": "integer", + "example": 2149 + }, + "title": { + "type": "string", + "example": "FM" + }, + "fideId": { + "type": "integer", + "example": 3408230 + }, + "fed": { + "type": "string", + "example": "CHI" + } + } + }, + "BroadcastRound": { + "example": { + "round": { + "id": "BueO56UJ", + "name": "Finals Day 1", + "slug": "finals-day-1", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/finals-day-1/BueO56UJ", + "createdAt": 1525789431889 + }, + "tour": { + "id": "QYiOYnl1", + "name": "New in Chess Classic | Finals", + "slug": "new-in-chess-classic--finals", + "description": "Match for 1st 2nd and 3rd place.", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/phgcXuBl", + "createdAt": 1525789431889 + }, + "study": { + "writeable": true + }, + "games": [ + { + "id": "GRjidNTw", + "name": "Martin Fargac - Vit Kostka", + "ongoing": true, + "res": "*", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/round-4/iCEwAzEX/GRjidNTw" + }, + { + "id": "81TcKCWT", + "name": "Pavel Zabystrzan - Kilian Slovak", + "res": "½-½", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/round-4/iCEwAzEX/tJpK7gbl" + }, + { + "id": "xEfufedI", + "name": "Roman Pilch - Bartolomej Buchta", + "res": "1-0", + "url": "https://lichess.org/broadcast/new-in-chess-classic--finals/round-4/iCEwAzEX/xEfufedI" + } + ] + } + }, + "BroadcastPgnPush": { + "type": "object", + "properties": { + "games": { + "type": "array", + "items": { + "type": "object", + "properties": { + "tags": { + "type": "object" + }, + "moves": { + "type": "integer" + }, + "error": { + "type": "string" + } + } + } + } + } + }, + "BroadcastMyRound": { + "example": { + "tour": { + "description": "April 18th - 28th | 10-round Swiss | Classical time control", + "id": "x7WskVz3", + "name": "Moonway Chess Festival", + "tier": "high", + "slug": "moonway-chess-festival" + }, + "round": { + "finished": true, + "id": "LXfsdxuf", + "name": "Round 5", + "slug": "round-5", + "startsAt": 1682168400000, + "url": "https://lichess.org/broadcast/moonway-chess-festival/round-5/LXfsdxuf" + }, + "study": { + "writeable": true + } + } + }, + "Simul": { + "example": { + "id": "pDGbxhUe", + "name": "GM ChessWeeb", + "fullName": "GM ChessWeeb simul", + "host": { + "id": "chessweeb", + "name": "ChessWeeb", + "rating": 1500, + "title": "GM" + }, + "isCreated": false, + "isFinished": true, + "isRunning": false, + "estimatedStartAt": 1620029815106, + "startedAt": 1620029815106, + "finishedAt": 1620029937283, + "nbApplicants": 0, + "nbPairings": 24, + "text": "", + "variants": [ + { + "icon": "+", + "key": "standard", + "name": "Standard" + } + ] + } + }, + "Team": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "coders" + }, + "name": { + "type": "string", + "example": "Coders" + }, + "description": { + "type": "string", + "example": "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": { + "type": "boolean", + "example": false + }, + "leaders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LightUser" + } + }, + "nbMembers": { + "type": "integer", + "example": 3129 + } + } + }, + "TeamPaginatorJson": { + "type": "object", + "properties": { + "currentPage": { + "type": "number", + "example": 4 + }, + "maxPerPage": { + "type": "number", + "example": 15 + }, + "currentPageResults": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Team" + } + }, + "nbResults": { + "type": "number", + "example": 205194 + }, + "previousPage": { + "type": [ + "number", + null + ], + "example": 3 + }, + "nextPage": { + "type": [ + "number", + null + ], + "example": 5 + }, + "nbPages": { + "type": "number", + "example": 13680 + } + } + }, + "TeamRequest": { + "type": "object", + "properties": { + "teamId": { + "type": "string", + "example": "coders" + }, + "userId": { + "type": "string", + "example": "thibault" + }, + "date": { + "type": "number", + "example": 1514505150384 + }, + "message": { + "type": "string", + "example": "Hello, I would like to join the team!" + } + } + }, + "TeamRequestWithUser": { + "type": "object", + "properties": { + "request": { + "$ref": "#/components/schemas/TeamRequest" + }, + "user": { + "$ref": "#/components/schemas/User" + } + } + }, + "Crosstable": { + "example": { + "users": { + "neio": 201.5, + "thibault": 144.5 + }, + "nbGames": 346, + "matchup": { + "users": { + "neio": 44, + "thibault": 43 + }, + "nbGames": 87 + } + } + }, + "LightUserOnline": { + "allOf": [ + { + "$ref": "#/components/schemas/LightUser" + }, + { + "properties": { + "online": { + "type": "boolean" + } + } + } + ] + }, + "UserNote": { + "type": "object", + "properties": { + "from": { + "$ref": "#/components/schemas/LightUser" + }, + "to": { + "$ref": "#/components/schemas/LightUser" + }, + "text": { + "type": "string", + "example": "This is a note" + }, + "date": { + "type": "integer", + "format": "int64", + "example": 1290415680000 + } + } + }, + "GameEventInfo": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "source": { + "type": "string", + "enum": [ + "lobby", + "friend", + "ai", + "api", + "tournament", + "position", + "import", + "importlive", + "simul", + "relay", + "pool", + "swiss" + ] + }, + "status": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "enum": [ + 10, + 20, + 25, + 30, + 31, + 32, + 33, + 34, + 35, + 36, + 37, + 38, + 60 + ] + }, + "name": { + "$ref": "#/components/schemas/GameStatus" + } + } + }, + "winner": { + "type": "string", + "enum": [ + "white", + "black" + ] + }, + "compat": { + "type": "object", + "properties": { + "bot": { + "type": "boolean" + }, + "board": { + "type": "boolean" + } + } + } + } + }, + "GameStartEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameStart" + }, + "game": { + "$ref": "#/components/schemas/GameEventInfo" + } + }, + "example": { + "type": "gameStart", + "game": { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "rating": 1790, + "username": "Philippe" + }, + "perf": "correspondence", + "rated": true, + "secondsLeft": 1209600, + "source": "friend", + "status": { + "id": 20, + "name": "started" + }, + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + }, + "compat": { + "bot": false, + "board": true + }, + "id": "rCRw1AuO" + } + } + }, + "GameFinishEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameFinish" + }, + "game": { + "$ref": "#/components/schemas/GameEventInfo" + } + }, + "example": { + "type": "gameFinish", + "game": { + "gameId": "rCRw1AuO", + "fullId": "rCRw1AuOvonq", + "color": "black", + "fen": "r1bqkbnr/pppp2pp/2n1pp2/8/8/3PP3/PPPB1PPP/RN1QKBNR w KQkq - 2 4", + "hasMoved": true, + "isMyTurn": false, + "lastMove": "b8c6", + "opponent": { + "id": "philippe", + "username": "Philippe", + "rating": 1790, + "ratingDiff": -12 + }, + "perf": "correspondence", + "rated": true, + "secondsLeft": 1209600, + "source": "friend", + "status": { + "id": 31, + "name": "resign" + }, + "speed": "correspondence", + "variant": { + "key": "standard", + "name": "Standard" + }, + "compat": { + "bot": false, + "board": true + }, + "winner": "black", + "ratingDiff": 8, + "id": "rCRw1AuO" + } + } + }, + "ChallengeUser": { + "allOf": [ + { + "$ref": "#/components/schemas/LightUser" + } + ], + "properties": { + "rating": { + "type": "number" + }, + "provisional": { + "type": "boolean" + }, + "online": { + "type": "boolean" + } + } + }, + "ChallengeJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "created", + "offline", + "canceled", + "declined", + "accepted" + ] + }, + "challenger": { + "$ref": "#/components/schemas/ChallengeUser" + }, + "destUser": { + "oneOf": [ + { + "$ref": "#/components/schemas/ChallengeUser" + }, + { + "type": null + } + ] + }, + "variant": { + "$ref": "#/components/schemas/Variant" + }, + "rated": { + "type": "boolean" + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "timeControl": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "clock" + }, + "limit": { + "type": "number" + }, + "increment": { + "type": "number" + }, + "show": { + "example": "5+2", + "type": "string" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "correspondence" + }, + "daysPerTurn": { + "type": "number" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "unlimited" + } + }, + "additionalProperties": false + } + ] + }, + "color": { + "type": "string", + "enum": [ + "white", + "black", + "random" + ] + }, + "perf": { + "type": "object", + "properties": { + "icon": { + "type": "string" + }, + "name": { + "type": "string" + } + } + }, + "direction": { + "type": "string", + "enum": [ + "in", + "out" + ] + }, + "initialFen": { + "type": "string" + }, + "declineReason": { + "type": "string", + "description": "Human readable, possibly translated reason why the challenge was declined." + }, + "declineReasonKey": { + "type": "string", + "description": "Untranslated, computer-matchable reason why the challenge was declined." + } + }, + "required": [ + "id", + "url", + "status", + "challenger", + "destUser", + "variant", + "rated", + "speed", + "timeControl", + "color", + "perf" + ], + "example": { + "id": "VU0nyvsW", + "url": "https://lichess.org/VU0nyvsW", + "color": "random", + "direction": "out", + "timeControl": { + "increment": 2, + "limit": 300, + "show": "5+2", + "type": "clock" + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "challenger": { + "id": "thibot", + "name": "thibot", + "online": true, + "provisional": false, + "rating": 1940, + "title": "BOT" + }, + "destUser": { + "id": "leelachess", + "name": "LeelaChess", + "online": true, + "provisional": true, + "rating": 2670, + "title": "BOT" + }, + "perf": { + "icon": ";", + "name": "Correspondence" + }, + "rated": true, + "speed": "blitz", + "status": "created" + } + }, + "ChallengeEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challenge" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeJson" + } + } + }, + "ChallengeCanceledEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challengeCanceled" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeJson" + } + }, + "example": { + "type": "challengeCanceled", + "challenge": { + "id": "7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status": "canceled", + "compat": { + "bot": false, + "board": true + }, + "challenger": { + "id": "lovlas", + "name": "Lovlas", + "title": "IM", + "rating": 2506, + "patron": true, + "online": true, + "lag": 24 + }, + "destUser": { + "id": "thibot", + "name": "thibot", + "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", + "finalColor": "black", + "speed": "rapid", + "perf": { + "icon": "#", + "name": "Rapid" + } + } + } + }, + "ChallengeCanceledJson": { + "type": "object", + "properties": { + "id": { + "type": "string" + } + }, + "example": { + "id": "VU0nyvsW" + } + }, + "ChallengeDeclinedEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "challengeDeclined" + }, + "challenge": { + "$ref": "#/components/schemas/ChallengeCanceledJson" + } + }, + "example": { + "type": "challengeDeclined", + "challenge": { + "id": "7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status": "declined", + "compat": { + "bot": false, + "board": true + }, + "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", + "finalColor": "white", + "speed": "rapid", + "perf": { + "icon": "#", + "name": "Rapid" + }, + "declineReason": "I'm not accepting challenges at the moment.", + "declineReasonKey": "generic" + } + } + }, + "GameEventPlayer": { + "type": "object", + "properties": { + "aiLevel": { + "type": "number" + }, + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "title": { + "type": [ + "string", + null + ] + }, + "rating": { + "type": "number" + }, + "provisional": { + "type": "boolean" + } + } + }, + "GameStateEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameState" + }, + "moves": { + "type": "string", + "description": "Current moves in UCI format" + }, + "wtime": { + "type": "integer", + "description": "Integer of milliseconds White has left on the clock" + }, + "btime": { + "type": "integer", + "description": "Integer of milliseconds Black has left on the clock" + }, + "winc": { + "type": "integer", + "description": "Integer of White Fisher increment." + }, + "binc": { + "type": "integer", + "description": "Integer of Black Fisher increment." + }, + "status": { + "$ref": "#/components/schemas/GameStatus" + }, + "winner": { + "type": "string", + "description": "Color of the winner, if any" + }, + "wdraw": { + "type": "boolean", + "description": "true if white is offering draw, else omitted" + }, + "bdraw": { + "type": "boolean", + "description": "true if black is offering draw, else omitted" + }, + "wtakeback": { + "type": "boolean", + "description": "true if white is proposing takeback, else omitted" + }, + "btakeback": { + "type": "boolean", + "description": "true if black is proposing takeback, else omitted" + } + }, + "required": [ + "type", + "moves", + "wtime", + "btime", + "winc", + "binc", + "status" + ], + "example": { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "wdraw": false, + "bdraw": false, + "status": "started" + } + }, + "GameFullEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "gameFull" + }, + "id": { + "type": "string" + }, + "variant": { + "$ref": "#/components/schemas/Variant" + }, + "clock": { + "oneOf": [ + { + "$ref": "#/components/schemas/Clock" + }, + { + "type": null + } + ] + }, + "speed": { + "$ref": "#/components/schemas/Speed" + }, + "perf": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Translated perf name (e.g. \"Classical\" or \"Blitz\")" + } + } + }, + "rated": { + "type": "boolean" + }, + "createdAt": { + "type": "number", + "format": "int64" + }, + "white": { + "$ref": "#/components/schemas/GameEventPlayer" + }, + "black": { + "$ref": "#/components/schemas/GameEventPlayer" + }, + "initialFen": { + "type": "string", + "default": "startpos" + }, + "state": { + "$ref": "#/components/schemas/GameStateEvent" + }, + "tournamentId": { + "type": "string" + } + }, + "required": [ + "type", + "id", + "variant", + "clock", + "speed", + "perf", + "rated", + "createdAt", + "white", + "black", + "initialFen", + "state" + ], + "example": { + "type": "gameFull", + "id": "5IrD6Gzz", + "rated": true, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "clock": { + "initial": 1200000, + "increment": 10000 + }, + "speed": "classical", + "perf": { + "name": "Classical" + }, + "createdAt": 1523825103562, + "white": { + "id": "lovlas", + "name": "lovlas", + "provisional": false, + "rating": 2500, + "title": "IM" + }, + "black": { + "id": "leela", + "name": "leela", + "rating": 2390 + }, + "initialFen": "startpos", + "state": { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "wdraw": false, + "bdraw": false, + "status": "started" + } + } + }, + "ChatLineEvent": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "chatLine" + }, + "room": { + "type": "string", + "enum": [ + "player", + "spectator" + ] + }, + "username": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "room", + "username", + "text" + ], + "example": { + "type": "chatLine", + "username": "thibault", + "text": "Good luck, have fun", + "room": "player" + } + }, + "OpponentGone": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "opponentGone" + }, + "gone": { + "type": "boolean" + }, + "claimWinInSeconds": { + "type": "number" + } + }, + "required": [ + "type", + "gone" + ], + "example": { + "type": "opponentGone", + "gone": true, + "claimWinInSeconds": 8 + } + }, + "NotFound": { + "properties": { + "error": { + "type": "string" + } + }, + "example": { + "error": "Not found." + } + }, + "GameChat": { + "example": [ + { + "text": "Takeback sent", + "user": "lichess" + }, + { + "text": "Takeback accepted", + "user": "lichess" + }, + { + "text": "Good game, well played", + "user": "thibault" + } + ] + }, + "ChallengeOpenJson": { + "example": { + "id": "VU0nyvsW", + "url": "https://lichess.org/VU0nyvsW", + "urlWhite": "https://lichess.org/VU0nyvsW?color=white", + "urlBlack": "https://lichess.org/VU0nyvsW?color=black", + "color": "random", + "direction": "out", + "timeControl": { + "increment": 2, + "limit": 300, + "show": "5+2", + "type": "clock" + }, + "variant": { + "key": "standard", + "name": "Standard", + "short": "Std" + }, + "challenger": { + "id": "thibot", + "name": "thibot", + "online": true, + "provisional": false, + "rating": 1940, + "title": "BOT" + }, + "destUser": { + "id": "leelachess", + "name": "LeelaChess", + "online": true, + "provisional": true, + "rating": 2670, + "title": "BOT" + }, + "perf": { + "icon": ";", + "name": "Correspondence" + }, + "rated": true, + "speed": "blitz", + "status": "created" + } + }, + "BulkPairing": { + "example": { + "id": "RVAcwgg7", + "games": [ + { + "id": "NKop9IyD", + "black": "lizen1", + "white": "thibault" + }, + { + "id": "KT8374ut", + "black": "lizen3", + "white": "lizen2" + }, + { + "id": "wInQr8Sk", + "black": "lizen5", + "white": "lizen4" + } + ], + "variant": "standard", + "clock": { + "increment": 0, + "limit": 300 + }, + "pairAt": 1612289869919, + "pairedAt": null, + "rated": false, + "startClocksAt": 1612200422971, + "scheduledAt": 1612203514628 + } + }, + "UciVariant": { + "type": "string", + "enum": [ + "chess", + "crazyhouse", + "antichess", + "atomic", + "horde", + "kingofthehill", + "racingkings", + "3check" + ], + "example": "chess", + "default": "chess" + }, + "ExternalEngine": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique engine registration ID.", + "example": "eei_aTKImBJOnv6j" + }, + "name": { + "type": "string", + "description": "Display name of the engine.", + "example": "Stockfish 15", + "minLength": 3, + "maxLength": 200 + }, + "clientSecret": { + "type": "string", + "description": "A secret token that can be used to\n[*request* analysis](#tag/External-engine/operation/apiExternalEngineAnalyse)\nfrom this external engine.\n", + "example": "ees_mdF2hK0hlKGSPeC6" + }, + "userId": { + "type": "string", + "description": "The user this engine has been registered for.", + "example": "thibault" + }, + "maxThreads": { + "type": "integer", + "description": "Maximum number of available threads.", + "example": 8, + "minimum": 1, + "maximum": 65536 + }, + "maxHash": { + "type": "integer", + "description": "Maximum available hash table size, in MiB.", + "example": 2048, + "minimum": 1, + "maximum": 1048576 + }, + "defaultDepth": { + "type": "integer", + "description": "Estimated depth of normal search.", + "example": 24, + "minimum": 0, + "maximum": 246 + }, + "variants": { + "type": "array", + "description": "List of supported chess variants.", + "example": [ + "chess" + ], + "items": { + "$ref": "#/components/schemas/UciVariant" + } + }, + "providerData": { + "type": "string", + "description": "Arbitrary data that the engine provider can use for identification\nor bookkeeping.\n\nUsers can read this information, but updating it requires knowing\nor changing the `providerSecret`.\n" + } + }, + "required": [ + "id", + "clientSecret", + "userId", + "name", + "maxThreads", + "maxHash", + "defaultDepth", + "variants" + ] + }, + "ExternalEngineRegistration": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Display name of the engine.", + "example": "Stockfish 15", + "minLength": 3, + "maxLength": 200 + }, + "maxThreads": { + "type": "integer", + "description": "Maximum number of available threads.", + "example": 8, + "minimum": 1, + "maximum": 65536 + }, + "maxHash": { + "type": "integer", + "description": "Maximum available hash table size, in MiB.", + "example": 2048, + "minimum": 1, + "maximum": 1048576 + }, + "defaultDepth": { + "type": "integer", + "description": "Estimated depth of normal search.", + "example": 24, + "minimum": 0, + "maximum": 246 + }, + "variants": { + "type": "array", + "description": "Optional list of supported chess variants.", + "items": { + "$ref": "#/components/schemas/UciVariant" + } + }, + "providerSecret": { + "type": "string", + "description": "A random token that can be used to\n[wait for analysis requests](#tag/External-engine/operation/apiExternalEngineAcquire)\nand provide analysis.\n\nThe engine provider should securely generate a random string.\n\nThe token will not be readable again, even by the user.\n\nThe analysis provider can register multiple engines with the same\ntoken, even for different users, and wait for analysis requests\nfrom any of them. In this case, the request must not be made via\nCORS, so that the token is not revealed to any of the users.\n", + "example": "Dee3uwieZei9ahpaici9bee2yahsai0K", + "minLength": 16, + "maxLength": 1024 + }, + "providerData": { + "type": "string", + "description": "Arbitrary data that the engine provider can use for identification\nor bookkeeping.\n\nUsers can read this information, but updating it requires knowing\nor changing the `providerSecret`.\n" + } + }, + "required": [ + "name", + "maxThreads", + "maxHash", + "defaultDepth", + "providerSecret" + ] + }, + "ExternalEngineWork": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "description": "Arbitary string that identifies the analysis session.\nProviders may wish to clear the hash table between sessions.\n", + "example": "abcd1234" + }, + "threads": { + "type": "integer", + "minimum": 1, + "description": "Number of threads to use for analysis.", + "example": 4 + }, + "hash": { + "type": "integer", + "minimum": 1, + "description": "Hash table size to use for analysis, in MiB.", + "example": 128 + }, + "infinite": { + "type": "boolean", + "description": "Request an infinite search (rather than roughly aiming for\n`defaultDepth`).\n", + "example": false + }, + "multiPv": { + "type": "integer", + "minimum": 1, + "maximum": 5, + "description": "Requested number of principal variations.", + "example": 1 + }, + "variant": { + "$ref": "#/components/schemas/UciVariant" + }, + "initialFen": { + "type": "string", + "description": "Initial position of the game.", + "example": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" + }, + "moves": { + "type": "array", + "description": "List of moves played from the initial position, in UCI notation.", + "items": { + "type": "string" + }, + "example": [ + "e2e4", + "g8f6" + ] + } + }, + "required": [ + "sessionId", + "threads", + "hash", + "multiPv", + "variant", + "initialFen", + "moves" + ] + }, + "OAuthError": { + "properties": { + "error": { + "type": "string", + "description": "The cause of the error." + }, + "error_description": { + "type": "string", + "description": "The reason why the request was rejected." + } + }, + "example": { + "error": "invalid_grant", + "error_description": "hash of code_verifier does not match code_challenge" + } + }, + "OpeningExplorerJson": { + "example": { + "opening": { + "eco": "D10", + "name": "Slav Defense: Exchange Variation" + }, + "white": 1443, + "draws": 3787, + "black": 1156, + "moves": [ + { + "uci": "c6d5", + "san": "cxd5", + "averageRating": 2423, + "white": 1443, + "draws": 3787, + "black": 1155, + "game": null + }, + { + "uci": "g8f6", + "san": "Nf6", + "averageRating": 2515, + "white": 0, + "draws": 0, + "black": 1, + "game": { + "id": "1EErB5jc", + "winner": "black", + "white": { + "name": "Drozdovskij, Yuri", + "rating": 2509 + }, + "black": { + "name": "Dobrov, Vladimir", + "rating": 2515 + }, + "year": 2006, + "month": "2006-01" + } + } + ], + "topGames": [ + { + "uci": "c6d5", + "id": "kN6d9l2i", + "winner": "black", + "white": { + "name": "Carlsen, M.", + "rating": 2881 + }, + "black": { + "name": "Anand, V.", + "rating": 2785 + }, + "year": 2014, + "month": "2014-06" + }, + { + "uci": "c6d5", + "id": "qeYPJL2y", + "winner": "white", + "white": { + "name": "So, W.", + "rating": 2778 + }, + "black": { + "name": "Carlsen, M.", + "rating": 2843 + }, + "year": 2018, + "month": "2018-06" + } + ], + "recentGames": [], + "history": [ + { + "month": "2017-04", + "black": 413538, + "draws": 38549, + "white": 429805 + }, + { + "month": "2017-05", + "black": 418542, + "draws": 39171, + "white": 434066 + } + ] + } + }, + "OpeningExplorerPlayerJson": { + "example": { + "white": 359, + "draws": 23, + "black": 273, + "moves": [ + { + "uci": "c2c4", + "san": "c4", + "averageOpponentRating": 1695, + "performance": 1744, + "white": 354, + "draws": 23, + "black": 266, + "game": null + }, + { + "uci": "c2c3", + "san": "c3", + "averageOpponentRating": 1796, + "performance": 1796, + "white": 2, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "e2e4", + "san": "e4", + "averageOpponentRating": 1762, + "performance": 1640, + "white": 1, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "g1f3", + "san": "Nf3", + "averageOpponentRating": 1496, + "performance": 1374, + "white": 1, + "draws": 0, + "black": 2, + "game": null + }, + { + "uci": "h2h3", + "san": "h3", + "averageOpponentRating": 1696, + "performance": 2496, + "white": 1, + "draws": 0, + "black": 0, + "game": { + "id": "zyI4GGKv", + "winner": "white", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "gocool99", + "rating": 1696 + }, + "white": { + "name": "revoof", + "rating": 1702 + }, + "year": 2020, + "month": "2020-07" + } + }, + { + "uci": "h2h4", + "san": "h4", + "averageOpponentRating": 1674, + "performance": 874, + "white": 0, + "draws": 0, + "black": 1, + "game": { + "id": "9vA24xBn", + "winner": "black", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "MentalBlood", + "rating": 1674 + }, + "white": { + "name": "revoof", + "rating": 1657 + }, + "year": 2020, + "month": "2020-06" + } + } + ], + "recentGames": [ + { + "uci": "c2c4", + "id": "BGLmUtv7", + "winner": "white", + "speed": "bullet", + "mode": "rated", + "black": { + "name": "yigithanyiigit", + "rating": 1227 + }, + "white": { + "name": "revoof", + "rating": 1717 + }, + "year": 2022, + "month": "2022-03" + } + ], + "opening": { + "eco": "D00", + "name": "Queen's Pawn Game" + }, + "queuePosition": 0 + } + }, + "MasterGamePgn": { + "example": "[Event \"Wch Blitz\"]\n[Site \"Astana\"]\n[Date \"2012.07.10\"]\n[Round \"23\"]\n[White \"Carlsen, Magnus\"]\n[Black \"Chadaev, Nikolay\"]\n[Result \"1-0\"]\n[WhiteElo \"2837\"]\n[BlackElo \"2580\"]\n\n1. e4 e5 2. f4 d5 3. exd5 exf4 4. Nf3 Nf6 5. c4 c6 6. d4 cxd5 7. c5 Nc6 8. Bb5 Be7 9. O-O O-O 10. Bxf4 Bg4 11. Nc3 Ne4 12. Qd3 Bf5 13. Qe3 Bf6 14. Bxc6 bxc6 15. Ne5 Bxe5 16. Bxe5 Bg6 17. Nxe4 Bxe4 18. Qg3 f6 19. Bd6 Re8 20. b4 Bg6 21. a4 a6 22. h4 Qd7 23. h5 Bxh5 24. Rxf6 Qg4 25. Qxg4 Bxg4 26. Rf4 Bh5 27. Raf1 h6 28. Be5 Ra7 29. b5 axb5 30. axb5 cxb5 31. c6 Raa8 32. c7 Kh7 33. Rb1 Be2 34. Rf7 Rg8 35. Re7 Bc4 36. Kh2 Rae8 37. Rd7 Ra8 38. Rb2 Raf8 39. g4 Ra8 40. Rf2 b4 41. Rff7 h5 42. Rxg7+ Rxg7 43. Rxg7+ 1-0\n" + }, + "Move": { + "type": "object", + "properties": { + "uci": { + "type": "string", + "example": "h7h8q" + }, + "san": { + "type": "string", + "example": "h8=Q+" + }, + "category": { + "type": "string", + "enum": [ + "loss", + "unknown", + "maybe-loss", + "blessed-loss", + "draw", + "cursed-win", + "maybe-win", + "win" + ] + }, + "dtz": { + "type": "integer", + "description": "DTZ50'' with rounding or null if unknown" + }, + "precise_dtz": { + "type": "integer", + "description": "DTZ50'' (only if guaranteed to be not rounded) or null if unknown\n" + }, + "dtm": { + "type": "integer", + "description": "Distance to mate (only for positions with not more than 5 pieces)" + }, + "zeroing": { + "type": "boolean" + }, + "checkmate": { + "type": "boolean" + }, + "stalemate": { + "type": "boolean" + }, + "variant_win": { + "type": "boolean" + }, + "variant_loss": { + "type": "boolean" + }, + "insufficient_material": { + "type": "boolean" + } + } + }, + "TablebaseJson": { + "type": "object", + "properties": { + "category": { + "type": "string", + "enum": [ + "win", + "unknown", + "maybe-win", + "cursed-win", + "draw", + "blessed-loss", + "maybe-loss", + "loss" + ], + "description": "`cursed-win` and `blessed-loss` means the 50-move rule prevents\nthe decisive result.\n\n`maybe-win` and `maybe-loss` means exact result is unknown due to\n[DTZ rounding](https://syzygy-tables.info/metrics#dtz), i.e., the\nwin or loss could also be prevented by the 50-move rule if\nthe user has deviated from the tablebase recommendation since the\nlast pawn move or capture.\n" + }, + "dtz": { + "type": "integer", + "description": "[DTZ50'' with rounding](https://syzygy-tables.info/metrics#dtz) or null if unknown\n" + }, + "precise_dtz": { + "type": "integer", + "description": "DTZ50'' (only if guaranteed to be not rounded) or null if unknown\n" + }, + "dtm": { + "type": "integer", + "description": "Distance to mate (only for positions with not more than 5 pieces)" + }, + "checkmate": { + "type": "boolean" + }, + "stalemate": { + "type": "boolean" + }, + "variant_win": { + "type": "boolean", + "description": "Only in chess variants" + }, + "variant_loss": { + "type": "boolean", + "description": "Only in chess variants" + }, + "insufficient_material": { + "type": "boolean" + }, + "moves": { + "type": "array", + "description": "Information about legal moves, best first", + "items": { + "$ref": "#/components/schemas/Move" + } + } + }, + "example": { + "dtz": 1, + "precise_dtz": 1, + "dtm": 17, + "checkmate": false, + "stalemate": false, + "variant_win": false, + "variant_loss": false, + "insufficient_material": false, + "category": "win", + "moves": [ + { + "uci": "h7h8q", + "san": "h8=Q+", + "dtz": -2, + "precise_dtz": -2, + "dtm": -16, + "zeroing": true, + "checkmate": false, + "stalemate": false, + "variant_win": false, + "variant_loss": false, + "insufficient_material": false, + "category": "loss" + } + ] + } + } + }, + "securitySchemes": { + "OAuth2": { + "type": "oauth2", + "description": "Read [the introduction for how to make authenticated requests](#section/Introduction/Authentication).\n", + "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", + "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](#operation/botAccountUpgrade)", + "web:mod": "Use moderator tools (within the bounds of your permissions)" + } + } + } + } + }, + "examples": { + "tvFeedFirst": { + "value": { + "t": "featured", + "d": { + "id": "qVSOPtMc", + "orientation": "black", + "players": [ + { + "color": "white", + "user": { + "name": "lizen9", + "id": "lizen9", + "title": "GM" + }, + "rating": 2531, + "seconds": 60 + }, + { + "color": "black", + "user": { + "name": "lizen29", + "title": "WGM", + "id": "lizen29" + }, + "rating": 2594, + "seconds": 60 + } + ], + "fen": "rnbqk1r1/ppp1ppbp/8/N2p2p1/8/1PQPP3/P1P2PPn/R1B1K1NR" + } + } + }, + "tvFeedFen": { + "value": { + "t": "fen", + "d": { + "fen": "5rk1/6p1/p4q2/4p3/2p5/2P2bNQ/PP3P1P/1K1RR3 w - - 4 32", + "lm": "h8g8", + "wc": 14, + "bc": 30 + } + } + }, + "broadcastPgnPushRequest": { + "value": "[White \"Rasmus Svane\"]\n[Black \"Rajat Makkar\"]\n[BlackElo \"2453\"]\n[BlackTeam \"France\"]\n[BlackTitle \"FM\"]\n[WhiteTeam \"Germany\"]\n[Result \"1-0\"]\n[WhiteElo \"2632\"]\n[WhiteTitle \"GM\"]\n\n1. d4 d5\n\n[White \"Joseph Girel\"]\n[Black \"Matthias Bluebaum\"]\n[BlackElo \"2658\"]\n[BlackTeam \"Germany\"]\n[BlackTitle \"GM\"]\n[WhiteTeam \"France\"]\n[Result \"0-1\"]\n[WhiteElo \"2484\"]\n[WhiteTitle \"IM\"]\n\n1. a8\n" + }, + "broadcastPgnPushResponse": { + "value": { + "games": [ + { + "tags": { + "White": "Rasmus Svane", + "Black": "Rajat Makkar", + "BlackElo": "2453", + "BlackTeam": "France", + "BlackTitle": "FM", + "WhiteTeam": "Germany", + "Result": "1-0", + "WhiteElo": "2632", + "WhiteTitle": "GM" + }, + "moves": 2 + }, + { + "tags": { + "White": "Joseph Girel", + "Black": "Matthias Bluebaum", + "BlackElo": "2658", + "BlackTeam": "Germany", + "BlackTitle": "GM", + "WhiteTeam": "France", + "Result": "0-1", + "WhiteElo": "2484", + "WhiteTitle": "IM" + }, + "error": "No move found: Pawn a8" + } + ] + } + } + } + } +} |