diff --git a/doc/specs/examples/_index.yaml b/doc/specs/examples/_index.yaml new file mode 100644 index 0000000..b4b0f58 --- /dev/null +++ b/doc/specs/examples/_index.yaml @@ -0,0 +1,35 @@ +challenge: + $ref: './challenge.yaml' + +challengeCanceled: + $ref: './challengeCanceled.yaml' + +challengeDeclined: + $ref: './challengeDeclined.yaml' + +gameStart: + $ref: './gameStart.yaml' + +gameFinish: + $ref: './gameFinish.yaml' + +gameFull: + $ref: './gameFull.yaml' + +gameState: + $ref: './gameState.yaml' + +chatLine: + $ref: './chatLine.yaml' + +chatLineSpectator: + $ref: './chatLineSpectator.yaml' + +opponentGoneTrue: + $ref: './opponentGoneTrue.yaml' + +opponentGoneFalse: + $ref: './opponentGoneFalse.yaml' + +gameStateResign: + $ref: './gameStateResign.yaml' diff --git a/doc/specs/examples/challenge.yaml b/doc/specs/examples/challenge.yaml new file mode 100644 index 0000000..395f8bd --- /dev/null +++ b/doc/specs/examples/challenge.yaml @@ -0,0 +1,48 @@ +value: { + "type":"challenge", + "challenge": { + "id":"7pGLxJ4F", + "url": "https://lichess.org/VU0nyvsW", + "status":"created", + "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": "white", + "speed":"rapid", + "perf": { + "icon":"#", + "name":"Rapid" + } + } +} diff --git a/doc/specs/examples/challengeCanceled.yaml b/doc/specs/examples/challengeCanceled.yaml new file mode 100644 index 0000000..1662bfc --- /dev/null +++ b/doc/specs/examples/challengeCanceled.yaml @@ -0,0 +1,50 @@ +value: { + "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" + } + } +} + + diff --git a/doc/specs/examples/challengeDeclined.yaml b/doc/specs/examples/challengeDeclined.yaml new file mode 100644 index 0000000..a13b3be --- /dev/null +++ b/doc/specs/examples/challengeDeclined.yaml @@ -0,0 +1,51 @@ +value: { + "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" + } +} diff --git a/doc/specs/examples/chatLine.yaml b/doc/specs/examples/chatLine.yaml new file mode 100644 index 0000000..96dee8e --- /dev/null +++ b/doc/specs/examples/chatLine.yaml @@ -0,0 +1,6 @@ +value: { + "type": "chatLine", + "username": "thibault", + "text": "Good luck, have fun", + "room": "player" +} diff --git a/doc/specs/examples/chatLineSpectator.yaml b/doc/specs/examples/chatLineSpectator.yaml new file mode 100644 index 0000000..dc5ccef --- /dev/null +++ b/doc/specs/examples/chatLineSpectator.yaml @@ -0,0 +1,6 @@ +value: { + "type": "chatLine", + "username": "lovlas", + "text": "!eval", + "room": "spectator" +} diff --git a/doc/specs/examples/gameFinish.yaml b/doc/specs/examples/gameFinish.yaml new file mode 100644 index 0000000..989955f --- /dev/null +++ b/doc/specs/examples/gameFinish.yaml @@ -0,0 +1,27 @@ +value: { + "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" + } +} diff --git a/doc/specs/examples/gameFull.yaml b/doc/specs/examples/gameFull.yaml new file mode 100644 index 0000000..6feac30 --- /dev/null +++ b/doc/specs/examples/gameFull.yaml @@ -0,0 +1,41 @@ +value: { + "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, + "status": "started" + } +} diff --git a/doc/specs/examples/gameStart.yaml b/doc/specs/examples/gameStart.yaml new file mode 100644 index 0000000..955d604 --- /dev/null +++ b/doc/specs/examples/gameStart.yaml @@ -0,0 +1,25 @@ +value: { + "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" + } +} diff --git a/doc/specs/examples/gameState.yaml b/doc/specs/examples/gameState.yaml new file mode 100644 index 0000000..f7b94ad --- /dev/null +++ b/doc/specs/examples/gameState.yaml @@ -0,0 +1,9 @@ +value: { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "status": "started" +} diff --git a/doc/specs/examples/gameStateResign.yaml b/doc/specs/examples/gameStateResign.yaml new file mode 100644 index 0000000..ff667fc --- /dev/null +++ b/doc/specs/examples/gameStateResign.yaml @@ -0,0 +1,10 @@ +value: { + "type": "gameState", + "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", + "wtime": 7598040, + "btime": 8395220, + "winc": 10000, + "binc": 10000, + "status": "resign", + "winner": "black" +} diff --git a/doc/specs/examples/opponentGoneFalse.yaml b/doc/specs/examples/opponentGoneFalse.yaml new file mode 100644 index 0000000..cc2fc70 --- /dev/null +++ b/doc/specs/examples/opponentGoneFalse.yaml @@ -0,0 +1,4 @@ +value: { + "type": "opponentGone", + "gone": false +} diff --git a/doc/specs/examples/opponentGoneTrue.yaml b/doc/specs/examples/opponentGoneTrue.yaml new file mode 100644 index 0000000..791a2bd --- /dev/null +++ b/doc/specs/examples/opponentGoneTrue.yaml @@ -0,0 +1,5 @@ +value: { + "type": "opponentGone", + "gone": true, + "claimWinInSeconds": 8 +} diff --git a/doc/specs/lichess-api.yaml b/doc/specs/lichess-api.yaml index 20b4efc..1848d86 100644 --- a/doc/specs/lichess-api.yaml +++ b/doc/specs/lichess-api.yaml @@ -244,11175 +244,433 @@ tags: [Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md). paths: /api/users/status: - get: - operationId: apiUsersStatus - summary: Get real-time users status - description: | - Read the `online`, `playing` and `streaming` flags of several users. - - This API is very fast and cheap on lichess side. - So you can call it quite often (like once every 5 seconds). - - Use it to track players and know when they're connected on lichess and playing games. - 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. - Defaults to `false` to preserve server resources. - 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 - } - ] + $ref: './tags/users/api-users-status.yaml' /api/player: - get: - operationId: player - summary: Get all top 10 - tags: - - Users - security: [] - description: | - Get the top 10 players for each speed and variant. - - See . - 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' + $ref: './tags/users/api-player.yaml' /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`). - There is no leaderboard for correspondence or puzzles. - - See . - 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' + $ref: './tags/users/api-player-top-nb-perfType.yaml' /api/user/{username}: - get: - operationId: apiUser - summary: Get user public data - description: | - Read public data of a user. - - If the request is [authenticated with OAuth2](#section/Introduction/Authentication), - then extra fields might be present in the response: `followable`, `following`, `blocking`, `followsYou`. - 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' + $ref: './tags/users/api-user-username.yaml' /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. - There is at most one entry per day. - Format of an entry is `[year, month, day, rating]`. - `month` starts at zero (January). - 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' + $ref: './tags/users/api-user-username-rating-history.yaml' /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. - Similar to the [performance pages on the website](https://lichess.org/@/thibault/perf/bullet). - 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' + $ref: './tags/users/api-user-username-perf-perf.yaml' /api/user/{username}/activity: - get: - operationId: apiUserActivity - summary: Get user activity - description: | - Read data to generate the activity feed of a user. - 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 + $ref: './tags/users/api-user-username-activity.yaml' /api/puzzle/daily: - get: - operationId: apiPuzzleDaily - summary: Get the daily puzzle - description: | - Get the daily Lichess puzzle in JSON format. - - Alternatively, you can [post it in your slack workspace](https://lichess.org/daily-puzzle-slack). - 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' + $ref: './tags/puzzles/api-puzzle-daily.yaml' /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' + $ref: './tags/puzzles/api-puzzle-id.yaml' /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. - - Puzzle activity is sorted by reverse chronological order (most recent first) - - We recommend streaming the response, for it can be very long. - 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' + $ref: './tags/puzzles/api-puzzle-activity.yaml' /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. - - Also includes all puzzle themes played, with aggregated results. - - Allows re-creating the [improvement/strengths](https://lichess.org/training/dashboard/30/improvementAreas) interfaces. - 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' + $ref: './tags/puzzles/api-puzzle-dashboard-days.yaml' /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. - - Contains the aggregated highscores, and the history of storm runs aggregated by days. - - Use `?days=0` if you only care about the highscores. - 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' + $ref: './tags/puzzles/api-storm-dashboard-username.yaml' /api/racer: - post: - operationId: racerPost - summary: Create and join a puzzle race - description: | - Create a new private [puzzle race](https://lichess.org/racer). - The Lichess user who creates the race must join the race page, - and manually start the race when enough players have joined. - - - - 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' + $ref: './tags/puzzles/api-racer.yaml' /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. - - The method is `POST` to allow a longer list of IDs to be sent in the request body. - - Please do not try to download all the Lichess users with this endpoint, or any other endpoint. - An API is not a way to fully export a website. We do not provide a full download of the Lichess users. - - This endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day. - 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' + $ref: './tags/users/api-users.yaml' /api/account: - get: - operationId: accountMe - summary: Get my profile - description: | - Public information about the logged in user. - 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' + $ref: './tags/account/api-account.yaml' /api/account/email: - get: - operationId: accountEmail - summary: Get my email address - description: | - Read the email address of the logged in user. - 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 + $ref: './tags/account/api-account-email.yaml' /api/account/preferences: - get: - operationId: account - summary: Get my preferences - description: | - Read the preferences of the logged in user. - - - - - - 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 + $ref: './tags/account/api-account-preferences.yaml' /api/account/kid: - get: - operationId: accountKid - summary: Get my kid mode status - description: | - Read the kid mode status of the logged in user. - - - - 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. - - - - 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' + $ref: './tags/account/api-account-kid.yaml' /api/timeline: - get: - operationId: timeline - summary: Get my timeline - description: | - Get the timeline events of the logged in user. - 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' + $ref: './tags/account/api-timeline.yaml' /game/export/{gameId}: - get: - operationId: gamePgn - summary: Export one game - description: | - Download one game in either PGN or JSON format. - - Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: true - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: true - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: true - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: true - - in: query - name: literate - description: | - Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. - - Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` - schema: - type: boolean - default: false - - in: query - name: players - description: | - URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. - Example: - 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' + $ref: './tags/games/game-export-gameId.yaml' /api/user/{username}/current-game: - get: - operationId: apiUserCurrentGame - summary: Export ongoing game of a user - description: | - Download the ongoing game, or the last game played, of a user. - Available in either PGN or JSON format. - - Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: true - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: true - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: true - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: false - - in: query - name: literate - description: | - Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. - - Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` - schema: - type: boolean - default: false - - in: query - name: players - description: | - URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. - Example: - 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' + $ref: './tags/games/api-user-username-current-game.yaml' /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. - - Games are sorted by reverse chronological order (most recent first). - - We recommend streaming the response, for it can be very long. - for instance has more than 500,000 games. - - The game stream is throttled, depending on who is making the request: - - Anonymous request: 20 games per second - - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second - - Authenticated, downloading your own games: 60 games per second - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: false - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: false - - in: query - name: ongoing - description: Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. - schema: - type: boolean - default: false - - in: query - name: finished - description: Include finished games. Set to `false` to only get ongoing games. - schema: - type: boolean - default: true - - in: query - name: literate - description: | - Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. - - Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` - schema: - type: boolean - default: false - - in: query - name: lastFen - description: | - Include the FEN notation of the last position of the game. - - The response type must be set to `application/x-ndjson` by the request `Accept` header. - schema: - type: boolean - default: false - - in: query - name: players - description: | - URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. - Example: - 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' + $ref: './tags/games/api-games-user-username.yaml' /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. - - Games are sorted by reverse chronological order (most recent first) - - The method is `POST` so a longer list of IDs can be sent in the request body. - - 300 IDs can be submitted. - - Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: false - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: false - - in: query - name: literate - description: | - Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. - - Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` - schema: - type: boolean - default: false - - in: query - name: players - description: | - URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. - Example: - 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' + $ref: './tags/games/api-games-export-_ids.yaml' /api/stream/games-by-users: - post: - operationId: gamesByUsers - summary: Stream games of users - description: | - Stream the games played between a list of users, in real time. - Only games where **both players** are part of the list are included. - - The stream emits an event each time a game is started or finished. - - To also get all current ongoing games at the beginning of the stream, use the `withCurrentGames` flag. - - Games are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - - Maximum number of users: 300. - - The method is `POST` so a longer list of IDs can be sent in the request body. - tags: - - Games - security: [] - requestBody: - description: | - Up to 300 user IDs separated by commas. - Example: `aliquantus,chess-network,lovlas` - 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' + $ref: './tags/games/api-stream-games-by-users.yaml' /api/stream/games/{streamId}: - post: - operationId: gamesByIds - summary: Stream games by IDs - description: | - Creates a stream of games from an arbitrary streamId, and a list of game IDs. - - The stream first outputs the games that already exists, then emits an event each time a game is started or finished. - - Games are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - - Maximum number of games: 500 for anonymous requests, or 1000 for [OAuth2 authenticated](#section/Introduction/Authentication) requests. - - While the stream is open, it is possible to [add new game IDs to watch](#operation/gamesByIdsAdd). - tags: - - Games - security: [] - parameters: - - in: path - name: streamId - schema: - type: string - description: Arbitrary stream ID that you can later use to add game IDs to the stream. - example: "myAppName-someRandomId" - required: true - requestBody: - description: | - Up to 500 or 1000 game IDs separated by commas. - Example: `gameId01,gameId02,gameId03` - required: true - content: - text/plain: - schema: - type: string - responses: - "200": - description: The stream of the games matching the requested IDs. - headers: - Access-Control-Allow-Origin: - schema: - type: string - default: "'*'" - content: - application/x-ndjson: - schema: - $ref: '#/components/schemas/GameStream' + $ref: './tags/games/api-stream-games-streamId.yaml' /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. - The stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished. - tags: - - Games - security: [] - parameters: - - in: path - name: streamId - schema: - type: string - description: The stream ID you used to [create the stream](#operation/gamesByIds). - example: "myAppName-someRandomId" - required: true - requestBody: - description: | - Up to 500 or 1000 game IDs separated by commas. - Example: `gameId04,gameId05,gameId06` - required: true - content: - text/plain: - schema: - type: string - responses: - "200": - description: The game IDs have been added to the stream. - headers: - Access-Control-Allow-Origin: - schema: - type: string - default: "'*'" - content: - application/json: - schema: - $ref: '#/components/schemas/Ok' + $ref: './tags/games/api-stream-games-streamId-add.yaml' /api/account/playing: - get: - operationId: apiAccountPlaying - summary: Get my ongoing games - description: | - Get the ongoing games of the current user. - Real-time and correspondence games are included. - The most urgent games are listed first. - tags: - - Games - security: - - OAuth2: [] - parameters: - - in: query - name: nb - description: Max number of games to fetch - schema: - type: integer - default: 9 - minimum: 1 - maximum: 50 - responses: - "200": - description: The ongoing games of the logged in user. - headers: - Access-Control-Allow-Origin: - schema: - type: string - default: "'*'" - content: - application/json: - schema: - 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" } - } - ] - } + $ref: './tags/games/api-account-playing.yaml' /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). - - A description of the game is sent as a first message. - Then a message is sent each time a move is played. - Finally a description of the game is sent when it finishes, and the stream is closed. - - Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. - - No more than 8 game streams can be opened at the same time from the same IP address. - 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' + $ref: './tags/games/api-stream-game-id.yaml' /api/import: - post: - operationId: gameImport - summary: Import one game - description: | - Import a game from PGN. See . - - Rate limiting: 200 games per hour for OAuth requests, 100 games per hour for anonymous requests. - - To broadcast ongoing games, consider [pushing to a broadcast instead](#operation/broadcastPush). - - To analyse a position or a line, just construct an analysis board URL: - [https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+](https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+) - 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"} - + $ref: './tags/games/api-import.yaml' + /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' + $ref: './tags/games/api-games-export-imports.yaml' /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, - but also computer games and bot games. - - See [lichess.org/tv](https://lichess.org/tv). - 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" - } - } + $ref: './tags/tv/api-tv-channels.yaml' /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). - A summary of the game is sent as a first message, and when the featured game changes. - - Try it with `curl https://lichess.org/api/tv/feed`. - tags: - - TV - security: [] - responses: - "200": - description: The stream of the current TV game. - content: - application/x-ndjson: - schema: - example: { - "t": "featured", - "d": { - "id": "qVSOPtMc", - "orientation": "black", - "players": [ - { - "color": "white", - "user": { "name": "lizen9", "id": "lizen9", "title": "GM" }, - "rating": 2531 - }, - { - "color": "black", - "user": { "name": "lizen29", "title": "WGM", "id": "lizen29" }, - "rating": 2594 - } - ], - "fen": "rnbqk1r1/ppp1ppbp/8/N2p2p1/8/1PQPP3/P1P2PPn/R1B1K1NR" - } - } + $ref: './tags/tv/api-tv-feed.yaml' /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). - - Available in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request `Accept` header. - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - 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' + $ref: './tags/tv/api-tv-channel.yaml' /api/tournament: - get: - operationId: apiTournament - summary: Get current tournaments - description: | - Get recently finished, ongoing, and upcoming tournaments. - - This API is used to display the [Lichess tournament schedule](https://lichess.org/tournament). - 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. - - This endpoint mirrors the form on . - - You can create up to 12 public tournaments per day, or 24 private tournaments. - - A team battle can be created by specifying the `teamBattleByTeam` argument. - - Additional restrictions: - - clockTime + clockIncrement > 0 - - 15s and 0+1 variant tournaments cannot be rated - - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150 - 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 - # "conditions.titled": - # type: boolean - # description: Whether to require a title to enter the tournament - # default: false - 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. - You can also [generate user-specific entry codes](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code) - based on this password. - teamBattleByTeam: - type: string - description: | - Set the ID of a team you lead to create a team battle. - The other teams can be added using the [team battle edit endpoint](#operation/apiTournamentTeamBattlePost). - conditions.teamMember.teamId: - type: string - description: | - Restrict entry to members of a team. - - The teamId is the last part of a team URL, e.g. `https://lichess.org/team/coders` has teamId = `coders`. - - Leave empty to let everyone join the tournament. - - Do not use this to create team battles, use `teamBattleByTeam` instead. - conditions.minRating.rating: - 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. - If this list is non-empty, then usernames absent from this list will be forbidden to join. - Adding `%titled` to the list additionally allows any titled player to join. - Example: `thibault,german11,%titled` - 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' + $ref: './tags/arenatournaments/api-tournament.yaml' /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. - 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. - - Be mindful not to make important changes to ongoing tournaments. - - Can be used to update a team battle. - - Additional restrictions: - - clockTime + clockIncrement > 0 - - 15s and 0+1 variant tournaments cannot be rated - - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150 - 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. - If this list is non-empty, then usernames absent from this list will be forbidden to join. - Adding `%titled` to the list additionally allows any titled player to join. - Example: `thibault,german11,%titled` - 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' + $ref: './tags/arenatournaments/api-tournament-id.yaml' /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. - Also unpauses if you had previously [paused](#operation/apiTournamentWithdraw) the tournament. - 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. - Can also be a [user-specific entry code](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code) - generated and shared by the organizer. - 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, - even if they are not connected to the tournament page. - This expires after one minute, to avoid pairing a user who is long gone. - You may call "join" again to extend the waiting. - 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' + $ref: './tags/arenatournaments/api-tournament-id-join.yaml' /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. - It's possible to join again later. Points and streaks are preserved. - 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' + $ref: './tags/arenatournaments/api-tournament-id-withdraw.yaml' /api/tournament/{id}/terminate: - post: - operationId: apiTournamentTerminate - summary: Terminate an Arena tournament - description: | - Terminate an Arena tournament - 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' + $ref: './tags/arenatournaments/api-tournament-id-terminate.yaml' /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. - - To update the other attributes of a team battle, use the [tournament update endpoint](#operation/apiTournamentUpdate). - 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. - Make sure to always send the full list. - Teams that are not in the list will be removed from the team battle. - - Example: `coders,zhigalko_sergei-fan-club,hhSwTKZv` - nbLeaders: - 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' + $ref: './tags/arenatournaments/api-tournament-team-battle-id.yaml' /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. - - Games are sorted by reverse chronological order (most recent first). - - The game stream is throttled, depending on who is making the request: - - Anonymous request: 20 games per second - - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: false - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: false - 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' + $ref: './tags/arenatournaments/api-tournament-id-games.yaml' /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). - - **Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON)**, i.e. one JSON object per line. - - If called on an ongoing tournament, results can be inconsistent - due to ranking changes while the players are being streamed. - Use on finished tournaments for guaranteed consistency. - 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. - It's an expensive server computation that slows down the stream. - 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" - } + $ref: './tags/arenatournaments/api-tournament-id-results.yaml' /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). - 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" } } - ] - } - ] - } + $ref: './tags/arenatournaments/api-tournament-id-teams.yaml' /api/user/{username}/tournament/created: - get: - operationId: apiUserNameTournamentCreated - summary: Get tournaments created by a user - description: | - Get all tournaments created by a given user. - - Tournaments are sorted by reverse chronological order of start date (last starting first). - - Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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) - - You can add this parameter more than once to include tournaments in different statuses. - - Example: `?status=10&status=20` - 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' + $ref: './tags/arenatournaments/api-user-username-tournament-created.yaml' /api/swiss/new/{teamId}: - post: - operationId: apiSwissNew - summary: Create a new Swiss tournament - description: | - Create a Swiss tournament for your team. - - This endpoint mirrors the Swiss tournament form from your team pagee. - - You can create up to 12 tournaments per day. - - Additional restrictions: - - clock.limit + clock.increment > 0 - - 15s and 0+1 variant tournaments cannot be rated - 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. - - Set to 99999999 to manually schedule each round from the tournament UI. - - If empty or -1, a sensible value is picked automatically. - 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. - - Two usernames per line, separated by a space. - manualPairings: - type: string - description: | - Manual pairings for the next round. - - Two usernames per line, separated by a space. Example: - ``` - PlayerA PlayerB - PlayerC PlayerD - ``` - - To give a bye (1 point) to a player instead of a pairing, add a line like so: - ``` - PlayerE 1 - ``` - - Missing players will be considered absent and get zero points. - chatFor: - type: number - description: | - Who can read and write in the chat. - - 0 = No-one - - 10 = Only team leaders - - 20 = Only team members - - 30 = All Lichess players - 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. - If they failed to show up in a recent swiss event, they won't be able to enter yours. - This results in a better swiss experience for the players who actually show up. - default: false - conditions.allowList: - type: string - description: | - Predefined list of usernames that are allowed to join, separated by commas. - If this list is non-empty, then usernames absent from this list will be forbidden to join. - Adding `%titled` to the list additionally allows any titled player to join. - Example: `thibault,german11,%titled` - 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' + $ref: './tags/swisstournaments/api-swiss-new-teamId.yaml' /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. - 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' + $ref: './tags/swisstournaments/api-swiss-id.yaml' /api/swiss/{id}/edit: - post: - operationId: apiSwissUpdate - summary: Update a Swiss tournament - description: | - Update a Swiss tournament. - - Be mindful not to make important changes to ongoing tournaments. - - Additional restrictions: - - clock.limit + clock.increment > 0 - - 15s and 0+1 variant tournaments cannot be rated - 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. - - Set to 99999999 to manually schedule each round from the tournament UI, or [with the API](#tag/Swiss-tournaments/operation/apiSwissScheduleNextRound). - - If empty or -1, a sensible value is picked automatically. - 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. - - Two usernames per line, separated by a space. - manualPairings: - type: string - description: | - Manual pairings for the next round. - - Two usernames per line, separated by a space. - Present players without a valid pairing will be given a bye, which is worth 1 point. - Forfeited players will get 0 points. - chatFor: - type: number - description: | - Who can read and write in the chat. - - 0 = No-one - - 10 = Only team leaders - - 20 = Only team members - - 30 = All Lichess players - 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. - If they failed to show up in a recent swiss event, they won't be able to enter yours. - This results in a better swiss experience for the players who actually show up. - default: false - conditions.allowList: - type: string - description: | - Predefined list of usernames that are allowed to join, separated by commas. - If this list is non-empty, then usernames absent from this list will be forbidden to join. - Adding `%titled` to the list additionally allows any titled player to join. - Example: `thibault,german11,%titled` - 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' + $ref: './tags/swisstournaments/api-swiss-id-edit.yaml' /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. - - This sets the `roundInterval` field to `99999999`, i.e. manual scheduling. - - All further rounds will need to be manually scheduled, unless the `roundInterval` field is changed back to automatic scheduling. - 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' + $ref: './tags/swisstournaments/api-swiss-id-schedule-next-round.yaml' /api/swiss/{id}/join: - post: - operationId: apiSwissJoin - summary: Join a Swiss tournament - description: | - Join a Swiss tournament, possibly with a password. - 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' + $ref: './tags/swisstournaments/api-swiss-id-join.yaml' /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. - It's possible to join again later. Points are preserved. - 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' + $ref: './tags/swisstournaments/api-swiss-id-withdraw.yaml' /api/swiss/{id}/terminate: - post: - operationId: apiSwissTerminate - summary: Terminate a Swiss tournament - description: | - Terminate a Swiss tournament - 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' + $ref: './tags/swisstournaments/api-swiss-id-terminate.yaml' /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. - - Documentation: - - Example: - 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 + $ref: './tags/swisstournaments/swiss-id.trf.yaml' /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. - - Games are sorted by reverse chronological order (last round first). - - The game stream is throttled, depending on who is making the request: - - Anonymous request: 20 games per second - - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second - 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. - - Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - - Or in a `clocks` JSON field, as centisecond integers, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: evals - description: | - Include analysis evaluations and comments, when available. - - Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` - - Or in an `analysis` JSON field, depending on the response type. - schema: - type: boolean - default: false - - in: query - name: accuracy - description: | - Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. - schema: - type: boolean - default: false - - in: query - name: opening - description: | - Include the opening name. - - Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` - schema: - type: boolean - default: false - - in: query - name: division - description: | - Plies which mark the beginning of the middlegame and endgame. - Only available in JSON - schema: - type: boolean - default: false - 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' + $ref: './tags/swisstournaments/api-swiss-id-games.yaml' /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). - - Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - - If called on an ongoing tournament, results can be inconsistent - due to ranking changes while the players are being streamed. - Use on finished tournaments for guaranteed consistency. - 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 - } + $ref: './tags/swisstournaments/api-swiss-id-results.yaml' /api/team/{teamId}/swiss: - get: - operationId: apiTeamSwiss - summary: Get team swiss tournaments - description: | - Get all swiss tournaments of a team. - - Tournaments are sorted by reverse chronological order of start date (last starting first). - - Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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' + $ref: './tags/teams/api-team-teamId-swiss.yaml' /api/study/{studyId}/{chapterId}.pgn: - get: - operationId: studyChapterPgn - summary: Export one study chapter - description: | - Download one study chapter in PGN format. - 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. - - Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - schema: - type: boolean - default: true - - in: query - name: comments - description: | - Include analysis and annotator comments in the PGN moves, when available. - - Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` - schema: - type: boolean - default: true - - in: query - name: variations - description: | - Include non-mainline moves, when available. - - Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` - schema: - type: boolean - default: true - - in: query - name: source - description: | - Add a `Source` PGN tag with the study chapter URL. - - Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` - schema: - type: boolean - default: false - - in: query - name: orientation - description: | - Add a `Orientation` PGN tag with the chapter predefined orientation. - - Example: `[Orientation "white"]` - schema: - type: boolean - default: false - responses: - "200": - description: The chapter of the study. - content: - application/x-chess-pgn: - schema: - $ref: '#/components/schemas/StudyPgn' + $ref: './tags/studies/api-study-studyId-chapterId.pgn.yaml' /api/study/{studyId}.pgn: - get: - operationId: studyAllChaptersPgn - summary: Export all chapters - description: | - Download all chapters of a study in PGN format. - 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. - - Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - schema: - type: boolean - default: true - - in: query - name: comments - description: | - Include analysis and annotator comments in the PGN moves, when available. - - Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` - schema: - type: boolean - default: true - - in: query - name: variations - description: | - Include non-mainline moves, when available. - - Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` - schema: - type: boolean - default: true - - in: query - name: source - description: | - Add a `Source` PGN tag with the study chapter URL. - - Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` - schema: - type: boolean - default: false - - in: query - name: orientation - description: | - Add a `Orientation` PGN tag with the chapter predefined orientation. - - Example: `[Orientation "white"]` - 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`. - 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' + $ref: './tags/studies/api-study-studyId.pgn.yaml' /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. - - If the PGN contains multiple games (separated by 2 or more newlines) - then multiple chapters will be created within the study. - - Note that a study can contain at most 64 chapters. - 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. - If multiple chapters are created, the names will be infered from the PGN tags. - minLength: 1 - maxLength: 100 - pgn: - type: string - description: | - PGN to import. Can contain multiple games separated by 2 or more newlines. - 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 Swiss tournament failed. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + $ref: './tags/studies/api-study-studyId-import-pgn.yaml' /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. - - If authenticated, then all public, unlisted, and private studies are included. - - If not, only public (non-unlisted) studies are included. - 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. - - Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` - schema: - type: boolean - default: true - - in: query - name: comments - description: | - Include analysis and annotator comments in the PGN moves, when available. - - Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` - schema: - type: boolean - default: true - - in: query - name: variations - description: | - Include non-mainline moves, when available. - - Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` - schema: - type: boolean - default: true - - in: query - name: source - description: | - Add a `Source` PGN tag with the study chapter URL. - - Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` - schema: - type: boolean - default: false - - in: query - name: orientation - description: | - Add a `Orientation` PGN tag with the chapter predefined orientation. - - Example: `[Orientation "white"]` - schema: - type: boolean - default: false - responses: - "200": - description: The studies of the user. - content: - application/x-chess-pgn: - schema: - $ref: '#/components/schemas/StudyPgn' + $ref: './tags/studies/study-by-username-export.pgn.yaml' /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. - - If authenticated, then all public, unlisted, and private studies are included. - - If not, only public (non-unlisted) studies are included. - - Studies are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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' + $ref: './tags/studies/api-study-by-username.yaml' /api/broadcast: - get: - operationId: broadcastIndex - summary: Get official broadcasts - description: | - Get all incoming, ongoing, and finished official broadcasts. - The broadcasts are sorted by start date, most recent first. - - Broadcasts are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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' + $ref: './tags/broadcasts/api-broadcast.yaml' /broadcast/new: - post: - operationId: broadcastTourCreate - summary: Create a broadcast tournament - description: | - Create a new broadcast tournament to relay external games. - This endpoint accepts the same form data as the [web form](https://lichess.org/broadcast/new). - 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' + $ref: './tags/broadcasts/broadcast-new.yaml' /broadcast/{slug}/{broadcastTournamentId}: - get: - operationId: broadcastTourGet - summary: Get your broadcast tournament - description: | - Get information about a broadcast tournament. - tags: - - Broadcasts - security: - - OAuth2: ["study:read"] - parameters: - - in: path - name: slug - description: The broadcast tournament slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastTournamentId` is actually used. - required: true - schema: - type: string - - 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' + $ref: './tags/broadcasts/broadcast-slug-broadcastTournamentId.yaml' /broadcast/{broadcastTournamentId}/edit: - post: - operationId: broadcastTourUpdate - summary: Update your broadcast tournament - description: | - Update information about a broadcast tournament that you created. - This endpoint accepts the same form data as the web form. - All fields must be populated with data. Missing fields will override the broadcast with empty data. - 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' + $ref: './tags/broadcasts/broadcast-broadcastTournamentId-edit.yaml' /broadcast/{broadcastTournamentId}/new: - post: - operationId: broadcastRoundCreate - summary: Create a broadcast round - description: | - Create a new broadcast round to relay external games. - This endpoint accepts the same form data as the web form. - 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. - - Example: `Round 1` - syncUrl: - type: string - description: | - URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet. - - Example: `https://myserver.org/myevent/round-10/games.pgn` - - If the syncUrl is missing, then the broadcast needs to be fed by [pushing PGN to it](#operation/broadcastPush). - syncUrlRound: - type: string - description: | - Required if `syncUrl` contains a livechesscloud link. - startsAt: - type: integer - description: | - Timestamp in milliseconds of broadcast round start. Leave empty to manually start the broadcast round. - - Example: `1356998400070` - 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. - - Example: `900` (15 min) - minimum: 0 - maximum: 1800 - period: - type: integer - description: | - (Only for Admins) Waiting time for each poll. - minimum: 2 - maximum: 60 - finished: - type: boolean - description: | - Mark whether the round has been completed. - 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' + $ref: './tags/broadcasts/broadcast-broadcastTournamentId-new.yaml' /api/broadcast/{broadcastTournamentSlug}/{broadcastRoundSlug}/{broadcastRoundId}: - get: - operationId: broadcastRoundGet - summary: Get a broadcast round - description: | - Get information about a broadcast round. - tags: - - Broadcasts - 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' + $ref: './tags/broadcasts/api-broadcast-broadcastTournamentSlug-broadcastRoundSlug-broadcastRoundId.yaml' /broadcast/round/{broadcastRoundId}/edit: - post: - operationId: broadcastRoundUpdate - summary: Update your broadcast round - description: | - Update information about a broadcast round that you created. - This endpoint accepts the same form data as the web form. - All fields must be populated with data. Missing fields will override the broadcast with empty data. - For instance, if you omit `startDate`, then any pre-existing start date will be removed. - 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. - - Example: `Round 10` - syncUrl: - type: string - description: | - URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet. - - Example: `https://myserver.org/myevent/round-10/games.pgn` - syncUrlRound: - type: string - description: | - Required if `syncUrl` contains a livechesscloud link. - startsAt: - type: integer - description: | - Timestamp in milliseconds of broadcast start. Leave empty to manually start the broadcast. - - Example: `1356998400070` - 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. - - Example: `900` (15 min) - minimum: 0 - maximum: 1800 - period: - type: integer - description: | - (Only for Admins) Waiting time for each poll. - minimum: 2 - maximum: 60 - finished: - type: boolean - description: | - Mark whether the round has been completed. - 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' + $ref: './tags/broadcasts/broadcast-round-broadcastRoundId-edit.yaml' /broadcast/round/{broadcastRoundId}/push: - post: - operationId: broadcastPush - summary: Push PGN to your broadcast round - description: | - Update your broadcast with new PGN. - Only for broadcast without a source URL. - 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 - responses: - "200": - description: The broadcast was successfully updated. - headers: - Access-Control-Allow-Origin: - schema: - type: string - default: "'*'" - content: - application/json: - schema: - properties: - moves: - type: integer - example: - moves: 12 - "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" + $ref: './tags/broadcasts/broadcast-round-broadcastRoundId-push.yaml' /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. - - Then, it waits for new moves to be played. As soon as it happens, the entire PGN of the game is sent to the stream. - - The stream will also send PGNs when games are added to the tournament. - - This is the best way to get updates about an ongoing tournament. Streaming means no polling, - and no pollings means no latency, and minimum impact on the server. - 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' + $ref: './tags/broadcasts/api-stream-broadcast-round-broadcastRoundId.pgn.yaml' /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. - - You *could* poll this endpoint to get updates about a tournament, but it would be slow, - and very inneficient. - - Instead, consider [streaming the tournament](#operation/broadcastStreamRoundPgn) to get - a new PGN every time a game is updated, in real-time. - 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' + $ref: './tags/broadcasts/api-broadcast-round-broadcastRoundId.pgn.yaml' /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. - - If a `study:read` [OAuth token](#tag/OAuth) is provided, - the private rounds where the user is a contributor will be available. - - You may want to [download only the games of a single round](#operation/broadcastRoundPgn) instead. - 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' + $ref: './tags/broadcasts/api-broadcast-broadcastTournamentId.pgn.yaml' /api/broadcast/my-rounds: - get: - operationId: broadcastMyRoundsGet - summary: Get your broadcast rounds - description: | - Stream all broadcast rounds you are a member of. - Also includes broadcasts rounds you did not create, but were invited to. - Also includes broadcasts rounds where you're a non-writing member. See the `writeable` flag in the response. - Rounds are ordered by rank, which is roughly chronological, most recent first, slightly pondered with popularity. - 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' + $ref: './tags/broadcasts/api-broadcast-my-rounds.yaml' /api/simul: - get: - operationId: apiSimul - summary: Get current simuls - description: | - Get recently created, started, finished, simuls. - - Created and finished simul lists are not exhaustives, only those with - strong enough host will be listed, the same filter is used to display simuls on https://lichess.org/simul. - - When [authenticated with OAuth2](#section/Introduction/Authentication), the pending list will be populated with your created, but unstarted simuls. - tags: - - Simuls - security: [] - responses: - "200": - description: The list of simuls. - headers: - Access-Control-Allow-Origin: - schema: - type: string - default: "'*'" - content: - application/json: - schema: - type: object - properties: - pending: - type: array - items: - $ref: '#/components/schemas/Simul' - created: - type: array - items: - $ref: '#/components/schemas/Simul' - started: - type: array - items: - $ref: '#/components/schemas/Simul' - finished: - type: array - items: - $ref: '#/components/schemas/Simul' + $ref: './tags/simuls/api-simul.yaml' /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' + $ref: './tags/teams/api-team-teamId.yaml' /api/team/all: - get: - operationId: teamAll - summary: Get popular teams - description: | - Paginator of the most popular teams. - 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' + $ref: './tags/teams/api-team-all.yaml' /api/team/of/{username}: - get: - operationId: teamOfUsername - summary: Teams of a player - description: | - All the teams a player is a member of. - 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' + $ref: './tags/teams/api-team-of-username.yaml' /api/team/search: - get: - operationId: teamSearch - summary: Search teams - description: | - Paginator of team search results for a keyword. - 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' + $ref: './tags/teams/api-team-search.yaml' /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). - OAuth is only required if the list of members is private. - - Members are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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' + $ref: './tags/teams/api-team-teamId-users.yaml' /api/team/{teamId}/arena: - get: - operationId: apiTeamArena - summary: Get team Arena tournaments - description: | - Get all Arena tournaments relevant to a team. - - Tournaments are sorted by reverse chronological order of start date (last starting first). - - Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). - 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' + $ref: './tags/teams/api-team-teamId-arena.yaml' /team/{teamId}/join: - post: - operationId: teamIdJoin - summary: Join a team - description: | - Join a team. - If the team requires a password but the `password` field is incorrect, - then the call fails with `403 Forbidden`. - Similarly, if the team join policy requires a confirmation but the - `message` parameter is not given, then the call fails with - `403 Forbidden`. - 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' + $ref: './tags/teams/team-teamId-join.yaml' /team/{teamId}/quit: - post: - operationId: teamIdQuit - summary: Leave a team - description: | - Leave a team. - - - 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' + $ref: './tags/teams/team-teamId-quit.yaml' /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" - } - } - ] + $ref: './tags/teams/api-team-teamId-requests.yaml' /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' + $ref: './tags/teams/api-team-teamId-request-userId-accept.yaml' /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' + $ref: './tags/teams/api-team-teamId-request-userId-decline.yaml' /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. - - - 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' + $ref: './tags/teams/api-team-teamId-kick-userId.yaml' /team/{teamId}/pm-all: - post: - operationId: teamIdPmAll - summary: Message all members - description: | - Send a private message to all members of a team. - You must be a team leader with the "Messages" permission. - 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' + $ref: './tags/teams/team-teamId-pm-all.yaml' /api/streamer/live: - get: - operationId: streamerLive - summary: Get live streamers - description: | - Get basic info about currently streaming users. - - This API is very fast and cheap on lichess side. - So you can call it quite often (like once every 5 seconds). - 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" - } - } - ] + $ref: './tags/users/api-streamer-live.yaml' /api/crosstable/{user1}/{user2}: - get: - operationId: apiCrosstable - summary: Get crosstable - description: | - Get total number of games, and current score, of any two users. - - If the `matchup` flag is provided, and the users are currently playing, also gets the current match game number and scores. - 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' + $ref: './tags/users/api-crosstable-user1-user2.yaml' /api/player/autocomplete: - get: - operationId: apiPlayerAutocomplete - summary: Autocomplete usernames - description: | - Provides autocompletion options for an incomplete username. - 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 - - `true` returns an object with matching users - schema: - type: boolean - default: false - - in: query - name: friend - description: | - Returns followed players matching `term` if any, else returns other players. - Requires [OAuth](#tag/OAuth). - 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' + $ref: './tags/users/api-player-autocomplete.yaml' /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. - 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. - 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 - } - ] + $ref: './tags/users/api-user-username-note.yaml' /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). - 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' + $ref: './tags/relations/api-rel-following.yaml' /api/rel/follow/{username}: - post: - operationId: followUser - summary: Follow a player - description: | - Follow a player, adding them to your list of Lichess friends. - 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' + $ref: './tags/relations/api-rel-follow-username.yaml' /api/rel/unfollow/{username}: - post: - operationId: unfollowUser - summary: Unfollow a player - description: | - Unfollow a player, removing them from your list of Lichess friends. - 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' + $ref: './tags/relations/api-rel-unfollow-username.yaml' /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' - examples: - challenge: - $ref: '#/components/examples/challenge' - challengeCanceled: - $ref: '#/components/examples/challengeCanceled' - challengeDeclined: - $ref: '#/components/examples/challengeDeclined' - gameStart: - $ref: '#/components/examples/gameStart' - gameFinish: - $ref: '#/components/examples/gameFinish' - + $ref: './tags/board/api-stream-event.yaml' /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. - Example: 1500-1800 - 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' + $ref: './tags/board/api-board-seek.yaml' /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' - examples: - gameFull: - $ref: '#/components/examples/gameFull' - gameState: - $ref: '#/components/examples/gameState' - chatLine: - $ref: '#/components/examples/chatLine' - chatLineSpectator: - $ref: '#/components/examples/chatLineSpectator' - opponentGoneTrue: - $ref: '#/components/examples/opponentGoneTrue' - opponentGoneFalse: - $ref: '#/components/examples/opponentGoneFalse' - gameStateResign: - $ref: '#/components/examples/gameStateResign' - "404": - description: The game was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/NotFound' + $ref: './tags/board/api-board-game-stream-gameId.yaml' /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. - - The move can also contain a draw offer/agreement. - 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' + $ref: './tags/board/api-board-game-gameId-move-move.yaml' /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. - 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 - 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' + $ref: './tags/board/api-board-game-gameId-chat.yaml' /api/board/game/{gameId}/abort: - post: - operationId: boardGameAbort - summary: Abort a game - description: | - Abort a game being played with the Board API. - 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' + $ref: './tags/board/api-board-game-gameId-abort.yaml' /api/board/game/{gameId}/resign: - post: - operationId: boardGameResign - summary: Resign a game - description: | - Resign a game being played with the Board API. - 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' + $ref: './tags/board/api-board-game-gameId-resign.yaml' /api/board/game/{gameId}/draw/{accept}: - post: - operationId: boardGameDraw - summary: Handle draw offers - description: | - Create/accept/decline draw offers. - - `yes`: Offer a draw, or accept the opponent's draw offer. - - `no`: Decline a draw offer from the opponent. - 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' + $ref: './tags/board/api-board-game-gameId-draw-accept.yaml' /api/board/game/{gameId}/takeback/{accept}: - post: - operationId: boardGameTakeback - summary: Handle takeback offers - description: | - Create/accept/decline takebacks. - - `yes`: Propose a takeback, or accept the opponent's takeback offer. - - `no`: Decline a takeback offer from the opponent. - 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' + $ref: './tags/board/api-board-game-gameId-takeback-accept.yaml' /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. - 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' + $ref: './tags/board/api-board-game-gameId-claim-victory.yaml' /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. - Only available in arena tournaments that allow berserk, and before each player has made a move. - 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' + $ref: './tags/board/api-board-game-gameId-berserk.yaml' /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' + $ref: './tags/bot/api-bot-online.yaml' /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. - - The account **cannot have played any game** before becoming a Bot account. The upgrade is **irreversible**. The account will only be able to play as a Bot. - - To upgrade an account to Bot, use the [official lichess-bot client](https://github.com/lichess-bot-devs/lichess-bot), or follow these steps: - - Create an [API access token](https://lichess.org/account/oauth/token/create?scopes[]=bot:play) with "Play bot moves" permission. - - `curl -d '' https://lichess.org/api/bot/account/upgrade -H "Authorization: Bearer "` - - To know if an account has already been upgraded, use the [Get my profile API](#operation/accountMe): - the `title` field should be set to `BOT`. - 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' + $ref: './tags/bot/api-bot-account-upgrade.yaml' /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' - examples: - gameFull: - $ref: '#/components/examples/gameFull' - gameState: - $ref: '#/components/examples/gameState' - chatLine: - $ref: '#/components/examples/chatLine' - chatLineSpectator: - $ref: '#/components/examples/chatLineSpectator' - opponentGoneTrue: - $ref: '#/components/examples/opponentGoneTrue' - opponentGoneFalse: - $ref: '#/components/examples/opponentGoneFalse' - gameStateResign: - $ref: '#/components/examples/gameStateResign' - "404": - description: The bot game was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/NotFound' + $ref: './tags/bot/api-bot-game-stream-gameId.yaml' /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. - - The move can also contain a draw offer/agreement. - 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' + $ref: './tags/bot/api-bot-game-gameId-move-move.yaml' /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. - 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 - 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' + $ref: './tags/bot/api-bot-game-gameId-chat.yaml' /api/bot/game/{gameId}/abort: - post: - operationId: botGameAbort - summary: Abort a game - description: | - Abort a game being played with the Bot API. - 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' + $ref: './tags/bot/api-bot-game-gameId-abort.yaml' /api/bot/game/{gameId}/resign: - post: - operationId: botGameResign - summary: Resign a game - description: | - Resign a game being played with the Bot API. - 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' + $ref: './tags/bot/api-bot-game-gameId-resign.yaml' /api/bot/game/{gameId}/draw/{accept}: - post: - operationId: botGameDraw - summary: Handle draw offers in bot games - description: | - Create/accept/decline draw offers in bot games - - `yes`: Offer a draw, or accept the opponent's draw offer. - - `no`: Decline a draw offer from the opponent. - 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' - + $ref: './tags/bot/api-bot-game-gameId-draw-accept.yaml' /api/challenge: - get: - operationId: challengeList - summary: List your challenges - description: | - Get a list of challenges created by or targeted at you. - 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' + $ref: './tags/challenges/api-challenge.yaml' /api/challenge/{username}: - post: - operationId: challengeCreate - summary: Create a challenge - description: | - Challenge someone to play. The targeted player can choose to accept or decline. - - If the challenge is accepted, you will be notified on the [event stream](#operation/apiStreamEvent) - that a new game has started. The game ID will be the same as the challenge ID. - - Challenges for realtime games (not correspondence) expire after 20s if not accepted. - To prevent that, use the `keepAliveStream` flag described below. - 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). - The challenge is kept alive until the connection is closed by the client. - When the challenge is accepted, declined or canceled, a message of the form `{"done":"accepted"}` is sent, - then the connection is closed by the server. - If not set, the response is not streamed, and the challenge expires after 20s if not accepted. - rules: - type: string - enum: - - noAbort - - noRematch - - noGiveTime - - noClaimWin - - noEarlyDraw - description: | - Extra game rules separated by commas. - Example: `noAbort,noRematch` - 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' + $ref: './tags/challenges/api-challenge-username.yaml' /api/challenge/{challengeId}/accept: - post: - operationId: challengeAccept - summary: Accept a challenge - description: | - Accept an incoming challenge. - - You should receive a `gameStart` event on the [incoming events stream](#operation/apiStreamEvent). - 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' + $ref: './tags/challenges/api-challenge-challengeId-accept.yaml' /api/challenge/{challengeId}/decline: - post: - operationId: challengeDecline - summary: Decline a challenge - description: | - Decline an incoming challenge. - 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' + $ref: './tags/challenges/api-challenge-challengeId-decline.yaml' /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. - Note that the ID of a game is the same as the ID of the challenge that created it. - - Works for user challenges and open challenges alike. - 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' + $ref: './tags/challenges/api-challenge-challengeId-cancel.yaml' /api/challenge/ai: - post: - operationId: challengeAi - summary: Challenge the AI - description: | - Start a game with Lichess AI. - - You will be notified on the [event stream](#operation/apiStreamEvent) that a new game has started. - 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' + $ref: './tags/challenges/api-challenge-ai.yaml' /api/challenge/open: - post: - operationId: challengeOpen - summary: Open-ended challenge - description: | - Create a challenge that any 2 players can join. - - Share the URL of the challenge. the first 2 players to click it will be paired for a game. - - The response body also contains `whiteUrl` and `blackUrl`. - You can control which color each player gets by giving them these URLs, - instead of the main challenge URL. - - Open challenges expire after 24h. - - If the challenge creation is [authenticated with OAuth2](#section/Introduction/Authentication), - then you can use the [challenge cancel endpoint](#operation/challengeCancel) to cancel it. - - To directly pair 2 known players, use [this endpoint](#operation/bulkPairingList) instead. - 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. - Example: `noRematch,noGiveTime` - The `noAbort` rule is available for Lichess admins only - users: - type: string - description: | - Optional pair of usernames, separated by a comma. - If set, only these users will be allowed to join the game. - The first username gets the white pieces. - Example: `Username1,Username2` - 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' + $ref: './tags/challenges/api-challenge-open.yaml' /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. - - Requires the OAuth tokens of both players with `challenge:write` scope. - - If the clocks have already started, the call will have no effect. - 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' + $ref: './tags/challenges/api-challenge-gameId-start-clocks.yaml' /api/bulk-pairing: - get: - operationId: bulkPairingList - summary: View your bulk pairings - description: | - Get a list of bulk pairings you created. - 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. - - OAuth tokens are required for all paired players, with the `challenge:write` scope. - - You can schedule up to 500 games every 10 minutes. [Contact us](mailto:contact@lichess.org) if you need higher limits. - - If games have a real-time clock, each player must have only one pairing. - For correspondence games, players can have multiple pairings within the same bulk. - - The entire bulk is rejected if: - - a token is missing - - a token is present more than once (except in correspondence) - - a token lacks the `challenge:write` scope - - a player account is closed - - a player is paired more than once (except in correspondence) - - a bulk is already scheduled to start at the same time with the same player - - you have 20 scheduled bulks - - you have 1000 scheduled games - - Partial bulks are never created. Either it all fails, or it all succeeds. - When it fails, it does so with an error message explaining the issue. - Failed bulks are not counted in the rate limiting, they are free. - Fix the issues, manually or programmatically, then retry to schedule the bulk. - - A successful bulk creation returns a JSON bulk document. Its ID can be used for further operations. - 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,...`. - - The 2 tokens of the players of a game are separated with `:`. The first token gets the white pieces. Games are separated with `,`. - - Up to 1000 tokens can be sent, for a max of 500 games. - - Each token must be included at most once. - - Example: `token1:token2,token3:token4,token5:token6` - 'clock.limit': - type: number - description: | - Clock initial time in seconds. Example: `600` - minimum: 0 - maximum: 10800 - 'clock.increment': - type: integer - description: | - Clock increment in seconds. Example: `2` - 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. - Up to 7 days in the future. - Omit, or set to current date and time, to start the games immediately. - Example: `1612289869919` - type: integer - startClocksAt: - description: | - Date at which the clocks will be automatically started as a Unix timestamp in milliseconds. - Up to 7 days in the future. - Note that the clocks can start earlier than specified, if players start making moves in the game. - If omitted, the clocks will not start automatically. - Example: `1612289869919` - 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. - - `{opponent}` and `{game}` are placeholders that will be replaced with the opponent and the game URLs. - - You can omit this field to send the default message, - but if you set your own message, it must at least contain the `{game}` placeholder. - default: "Your game with {opponent} is ready: {game}." - rules: - type: string - enum: - - noAbort - - noRematch - - noGiveTime - - noClaimWin - - noEarlyDraw - description: | - Extra game rules separated by commas. - Example: `noAbort,noRematch` - 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' + $ref: './tags/bulkpairings/api-bulk-pairing.yaml' /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. - - This overrides the `startClocksAt` value of an existing bulk pairing. - - If the games have not yet been created (`bulk.pairAt` is in the future), then this does nothing. - - If the clocks have already started (`bulk.startClocksAt` is in the past), then this does nothing. - 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' + $ref: './tags/bulkpairings/api-bulk-pairing-id-start-clocks.yaml' /api/bulk-pairing/{id}: - get: - operationId: bulkPairingGet - summary: Show a bulk pairing - description: | - Get a single bulk pairing by its ID. - 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. - - If the games have already been created, then this does nothing. - - Canceling a bulk pairing does not refund the rate limit cost of that bulk pairing. - 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' - + $ref: './tags/bulkpairings/api-bulk-pairing-id.yaml' /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. - 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' + $ref: './tags/challenges/api-round-gameId-add-time-seconds.yaml' /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.* - - Create and obtain `challenge:write` tokens for multiple users. - - If a similar token already exists for a user, it is reused. This endpoint is idempotent. - 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' + $ref: './tags/challenges/api-token-admin-challenge.yaml' /inbox/{username}: - post: - operationId: inboxUsername - summary: Send a private message - description: | - Send a private message to another player. - 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' + $ref: './tags/messaging/inbox-username.yaml' /api/cloud-eval: - get: - operationId: apiCloudEval - summary: Get cloud evaluation of a position. - description: | - Get the cached evaluation of a position, if available. - - Opening positions have more chances of being available. There are about 15 million positions in the database. - - Up to 5 variations may be available. Variants are supported. - - Use this endpoint to fetch a few positions here and there. - If you want to download a lot of positions, [get the full list](https://database.lichess.org/#evals) from our exported database. - 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} - ] - } + $ref: './tags/analysis/api-cloud-eval.yaml' /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, - and the credentials required to use them. - 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 - and used on the analysis board. - - After registering, the provider should start waiting for analyis requests. - 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' + $ref: './tags/externalengine/api-external-engine.yaml' /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. - 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. - 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. - responses: - "200": - description: Engine successfully deleted - content: - application/json: - schema: - $ref: '#/components/schemas/Ok' + $ref: './tags/externalengine/api-external-engine-id.yaml' /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`** - - Request analysis from an external engine. - - Response content is streamed as [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). - The properties are based on the [UCI specification](https://backscattering.de/chess/uci/#engine). - Analysis stops when the client goes away, the requested limit - is reached, or the provider goes away. - 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 + $ref: './tags/externalengine/api-external-engine-id-analyse.yaml' /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`** - - Wait for an analysis requests to any of the external engines that - have been registered with the given `secret`. - - Uses long polling. - - After acquiring a request, the provider should immediately - [start streaming the results](#tag/External-engine/operation/apiExternalEngineSubmit). - 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: "'*'" + $ref: './tags/externalengine/api-external-engine-work.yaml' /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}`** - - Submit a stream of analysis as [UCI output](https://backscattering.de/chess/uci/#engine-info). - - * The engine should always be in `UCI_Chess960` mode. - * `UCI_AnalyseMode` enabled if available. - * It produces `info` with at least: - - `depth` - - `multipv` (between 1 and 5) - - `score` - - `nodes` - - `time` - - `pv` - - The server may close the connection at any time, indicating that - the requester has gone away and analysis should be stopped. - 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: "'*'" + $ref: './tags/externalengine/api-external-engine-work-id.yaml' /oauth: - get: - operationId: oauth - summary: Request authorization code - tags: - - OAuth - security: [] - description: | - OAuth2 authorization endpoint. - - Start the OAuth2 Authorization Code Flow with PKCE by securely - generating two random strings unique to each authorization - request: - * `code_verifier` - * `state` - - Store these in session storage. Make sure not to reveal `code_verifier` - to eavesdroppers. Do not show it in URLs, do not abuse `state` to store - it, do not send it over insecure connections. However it is fine if - the user themselves can extract `code_verifier`, which will always be - possible for fully client-side apps. - - Then send the user to this endpoint. They will be prompted to grant - authorization and then be redirected back to the given `redirect_uri`. - - If the authorization failed, the following query string parameters will - be appended to the redirection: - * `error`, in particular with value `access_denied` if the user - cancelled authorization - * `error_description` to aid debugging - * `state`, exactly as passed in the `state` parameter - - If the authorization succeeded, the following query string parameters - will be appended to the redirection: - * `code`, containing a fresh short-lived authorization code - * `state`, exactly as passed in the `state` parameter - - Next, to defend against cross site request forgery, check that the - returned `state` matches the `state` you originally generated. - - Finally, continue by using the authorization code to - [obtain an access token](#operation/apiToken). - 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. + $ref: './tags/oauth/oauth.yaml' /api/token: - post: - operationId: apiToken - summary: Obtain access token - tags: - - OAuth - security: [] - description: | - OAuth2 token endpoint. Exchanges an authorization code for an access token. - 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: "'*'" + $ref: './tags/oauth/api-token.yaml' /api/token/test: - post: - operationId: tokenTest - summary: Test multiple OAuth tokens - description: | - For up to 1000 OAuth tokens, - returns their associated user ID and scopes, - or `null` if the token is invalid. - - The method is `POST` so a longer list of tokens can be sent in the request body. - 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 - } + $ref: './tags/oauth/api-token-test.yaml' /masters: - servers: - - url: https://explorer.lichess.ovh - get: - operationId: openingExplorerMaster - summary: Masters database - description: | - **Endpoint: ** - - Example: `curl https://explorer.lichess.ovh/masters?play=d2d4,d7d5,c2c4,c7c6,c4d5` - 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. - Play additional moves starting from `fen`. - Required to find an opening name, if `fen` is not an exact match - for a named position. - 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' + $ref: './tags/openingexplorer/masters.yaml' /lichess: - servers: - - url: https://explorer.lichess.ovh - get: - operationId: openingExplorerLichess - summary: Lichess games - description: | - **Endpoint: ** - - Games sampled from all Lichess players. - - Example: `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` - 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. - Play additional moves starting from `fen`. - Required to find an opening name, if `fen` is not an exact match - for a named position. - 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. - Each group ranges from its value to the next higher - group in the enum (`0` from 0 to 999, `1000` from 1000 to 1199, - ..., `2500` from 2500 to any rating above). - 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 # or 8, depending on query - - 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' + $ref: './tags/openingexplorer/lichess.yaml' /player: - servers: - - url: https://explorer.lichess.ovh - get: - operationId: openingExplorerPlayer - summary: Player games - description: | - **Endpoint: ** - - Games of a Lichess player. - - Responds with a stream of [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). Will start indexing - on demand, immediately respond with the current results, and stream - more updates until indexing is complete. The stream is throttled - and deduplicated. Empty lines may be sent to avoid timeouts. - - Will index new games at most once per minute, and revisit previously - ongoing games at most once every day. - - Example: `curl https://explorer.lichess.ovh/player?player=revoof&color=white&play=d2d4,d7d5&recentGames=1` - 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. - Play additional moves starting from `fen`. - Required to find an opening name, if `fen` is not an exact match - for a named position. - 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' + $ref: './tags/openingexplorer/player.yaml' /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}`** - - Example: `curl https://explorer.lichess.ovh/masters/pgn/aAbqI4ey` - 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' + $ref: './tags/openingexplorer/master-pgn-gameId.yaml' /standard: - servers: - - url: https://tablebase.lichess.ovh - get: - operationId: tablebaseStandard - summary: Tablebase lookup - description: | - **Endpoint: ** - - Example: `curl http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1` - 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' + $ref: './tags/tablebase/standard.yaml' + /atomic: - servers: - - url: https://tablebase.lichess.ovh - get: - operationId: tablebaseAtomic - summary: Tablebase lookup for Atomic chess - description: | - **Endpoint: ** - 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: "'*'" + $ref: './tags/tablebase/atomic.yaml' /antichess: - servers: - - url: https://tablebase.lichess.ovh - get: - operationId: antichessAtomic - summary: Tablebase lookup for Antichess - description: | - **Endpoint: ** - 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: "'*'" + $ref: './tags/tablebase/antichess.yaml' + components: schemas: - VariantKey: - type: string - enum: - - standard - - chess960 - - crazyhouse - - antichess - - atomic - - horde - - kingOfTheHill - - racingKings - - threeCheck - - fromPosition - example: standard - default: standard - - Variant: - type: object - properties: - key: - $ref: '#/components/schemas/VariantKey' - name: - type: string - short: - type: string - - UciVariant: - type: string - enum: - - chess - - crazyhouse - - antichess - - atomic - - horde - - kingofthehill - - racingkings - - 3check - example: chess - default: chess - - Speed: - type: string - enum: - - ultraBullet - - bullet - - blitz - - rapid - - classical - - correspondence - - PerfType: - type: string - enum: - - ultraBullet - - bullet - - blitz - - rapid - - classical - - correspondence - - chess960 - - crazyhouse - - antichess - - atomic - - horde - - kingOfTheHill - - racingKings - - threeCheck - - Clock: - type: object - properties: - limit: - type: integer - increment: - type: integer - - 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 - - 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" - - 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" - } - - ChallengeCanceledJson: - type: object - properties: - id: - type: string - example: { - "id": "VU0nyvsW" - } - - 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 - } - - 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 - } - } - GamePgn: - example: | - [Event "Rated Blitz game"] - [Site "https://lichess.org/fY44h4OY"] - [Date "2018.03.29"] - [Round "-"] - [White "pveldman"] - [Black "thibault"] - [Result "1-0"] - [UTCDate "2018.03.29"] - [UTCTime "01:38:15"] - [WhiteElo "1610"] - [BlackElo "1601"] - [WhiteRatingDiff "+10"] - [BlackRatingDiff "-10"] - [Variant "Standard"] - [TimeControl "180+0"] - [ECO "C62"] - [Opening "Ruy Lopez: Steinitz Defense"] - [Termination "Normal"] - [Event "U1700 SuperBlitz Arena"] - - 1. 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 - MasterGamePgn: - example: | - [Event "Wch Blitz"] - [Site "Astana"] - [Date "2012.07.10"] - [Round "23"] - [White "Carlsen, Magnus"] - [Black "Chadaev, Nikolay"] - [Result "1-0"] - [WhiteElo "2837"] - [BlackElo "2580"] - - 1. 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 - StudyPgn: - example: | - [Event "All about the Sicilian Defense: Dragon Variation"] - [Site "https://lichess.org/study/8c8bmUfy/qwnXMwVC"] - [Result "*"] - [UTCDate "2017.06.25"] - [UTCTime "10:12:04"] - [Variant "Standard"] - [ECO "B76"] - [Opening "Sicilian Defense: Dragon Variation, Yugoslav Attack, Panov Variation"] - [Annotator "https://lichess.org/@/Francesco_Super"] - - { 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. } - 1. 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 * - - StudyMetadata: - example: { - "id": "WTvnkWAL", - "name": "Guess the move", - "createdAt": 1463756350225, - "updatedAt": 1469965025205 - } - - StudyImportPgnChapters: - example: { - "chapters": [{ - "id": "WTvnkWAL", - "name": "Game 2" - }], - } - - Title: - type: string - enum: [GM, WGM, IM, WIM, FM, WFM, NM, CM, WCM, WNM, LM, BOT] - example: NM - - 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 - - LightUserOnline: - allOf: - - $ref: '#/components/schemas/LightUser' - - properties: - online: - type: boolean - - 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 - - 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' - - 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 - - PlayTime: - type: object - properties: - total: - type: integer - example: 3296897 - tv: - type: integer - example: 12134 - - 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 - uscfRating: - type: integer - example: 1500 - ecfRating: - type: integer - example: 1500 - links: - type: string - example: "github.com/ornicar\r\ntwitter.com/ornicar" - - 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 - - User: - type: object - properties: - id: - type: string - example: georges - username: - type: string - example: Georges - perfs: - $ref: '#/components/schemas/Perfs' - createdAt: - type: integer - format: int64 - example: 1290415680000 - disabled: - type: boolean - example: false - tosViolation: - type: boolean - example: false - 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' - - 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 - following: - type: boolean - example: false - blocking: - type: boolean - example: false - followsYou: - type: boolean - example: false - - Crosstable: - example: { - "users": { - "neio": 201.5, - "thibault": 144.5 - }, - "nbGames": 346, - "matchup": { - "users": { - "neio": 44, - "thibault": 43 - }, - "nbGames": 87 - } - } - - GameChat: - example: [{ - "text": "Takeback sent", - "user": "lichess" - }, - { - "text": "Takeback accepted", - "user": "lichess" - }, - { - "text": "Good game, well played", - "user": "thibault" - }] - - 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" - } - } - } - - PuzzleRaceJson: - example: { - "id": "Kj1t0", - "url": "https://lichess.org/racer/Kj1t0" - } - - 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 - }, - ] - } - - RatingHistory: - example: [{"name": "Bullet","points":[[2011,0,8,1472],[2011,0,9,1332],[2011,8,12,1314]]},{"name": "Blitz","points":[[2011,7,29,1332]]}] - - 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" - } - } - } - - 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" - }, - ] - } - - 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 - - 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' - - ArenaStatus: - type: integer - description: | - 10: created, 20: started, 30: finished - 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' - - 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 - } - } - - 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 - } - } - - 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" - } - ] - } - - BroadcastForm: - type: object - properties: - name: - type: string - description: | - Name of the broadcast tournament. Length must be between 3 and 80 characters. - - Example: `Sinquefield Cup` - description: - type: string - description: | - Short description of the broadcast tournament. Length must be between 3 and 400 characters. - - Example: `An 11 round classical tournament featuring the 9 highest rated players in the world. Including Carlsen, Caruana, Ding, Aronian, Nakamura and more.` - 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. - - * `3` for normal - * `4` for high - * `5` for best - players: - description: | - Optional replace player names, ratings and titles. - - One line per player, formatted as such: - - `Original name; Replacement name; Optional replacement rating; Optional replacement title` - - Example: - - DrNykterstein;Magnus Carlsen;2863 - - AnishGiri;Anish Giri;2764;GM - required: - - name - - description - - autoLeaderboard - - - 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 - } - ] - } - - 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" - } - ] - } - - 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 - }, - } - - 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 - } - - 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 - the decisive result. - - `maybe-win` and `maybe-loss` means exact result is unknown due to - [DTZ rounding](https://syzygy-tables.info/metrics#dtz), i.e., the - win or loss could also be prevented by the 50-move rule if - the user has deviated from the tablebase recommendation since the - last pawn move or capture. - dtz: - type: integer - description: | - [DTZ50'' with rounding](https://syzygy-tables.info/metrics#dtz) or null if unknown - precise_dtz: - type: integer - description: | - DTZ50'' (only if guaranteed to be not rounded) or null if unknown - 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" - } - ] - } - - 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 - 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 - - 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' - - GameEventPlayer: - type: object - properties: - aiLevel: - type: number - id: - type: string - name: - type: string - title: - type: [string, 'null'] - rating: - type: number - provisional: - type: boolean - - 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 - - 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 - - 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 - - OpponentGone: - type: object - properties: - type: - type: string - const: opponentGone - gone: - type: boolean - claimWinInSeconds: - type: number - required: - - type - - gone - - 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' - - GameFinishEvent: - type: object - properties: - type: - type: string - const: gameFinish - game: - $ref: '#/components/schemas/GameEventInfo' - - 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' - - ChallengeDeclinedEvent: - type: object - properties: - type: - type: string - const: challengeDeclined - challenge: - $ref: '#/components/schemas/ChallengeCanceledJson' - - Ok: - properties: - ok: - type: boolean - example: - ok: true - - Error: - properties: - error: - type: string - description: The cause of the error. - example: - error: "This request is invalid because [...]" - - 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" - - NotFound: - properties: - error: - type: string - example: - error: "Not found." - - - SwissUnauthorisedEdit: - properties: - error: - type: string - example: - error: "This user cannot edit this swiss" - - 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 - } - ] - - 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' - #officialStockfish: - # type: boolean - # description: | - # Promises that the engine is a recent official Stockfish release. - # Can be considered for cloud evaluation. - # required: false - providerSecret: - type: string - description: | - A random token that can be used to - [wait for analysis requests](#tag/External-engine/operation/apiExternalEngineAcquire) - and provide analysis. - - The engine provider should securely generate a random string. - - The token will not be readable again, even by the user. - - The analysis provider can register multiple engines with the same - token, even for different users, and wait for analysis requests - from any of them. In this case, the request must not be made via - CORS, so that the token is not revealed to any of the users. - example: Dee3uwieZei9ahpaici9bee2yahsai0K - minLength: 16 - maxLength: 1024 - providerData: - type: string - description: | - Arbitrary data that the engine provider can use for identification - or bookkeeping. - - Users can read this information, but updating it requires knowing - or changing the `providerSecret`. - required: - - name - - maxThreads - - maxHash - - defaultDepth - - providerSecret - - 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 - [*request* analysis](#tag/External-engine/operation/apiExternalEngineAnalyse) - from this external engine. - 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 - or bookkeeping. - - Users can read this information, but updating it requires knowing - or changing the `providerSecret`. - required: - - id - - clientSecret - - userId - - name - - maxThreads - - maxHash - - defaultDepth - - variants - - ExternalEngineWork: - type: object - properties: - sessionId: - type: string - description: | - Arbitary string that identifies the analysis session. - Providers may wish to clear the hash table between sessions. - 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 - `defaultDepth`). - 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 - - 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 - } - } - } - + $ref: './schemas/_index.yaml' securitySchemes: OAuth2: type: oauth2 @@ -11447,306 +705,5 @@ components: "web:mod": Use moderator tools (within the bounds of your permissions) examples: - challenge: - value: { - "type":"challenge", - "challenge": { - "id":"7pGLxJ4F", - "url": "https://lichess.org/VU0nyvsW", - "status":"created", - "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": "white", - "speed":"rapid", - "perf": { - "icon":"#", - "name":"Rapid" - } - } - } - - challengeCanceled: - value: { - "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" - } - } - } - - challengeDeclined: - value: { - "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" - } - } - - gameStart: - value: { - "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" - } - } - - gameFinish: - value: { - "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" - } - } - - gameFull: - value: { - "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, - "status": "started" - } - } - - gameState: - value: { - "type": "gameState", - "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", - "wtime": 7598040, - "btime": 8395220, - "winc": 10000, - "binc": 10000, - "status": "started" - } - - chatLine: - value: { - "type": "chatLine", - "username": "thibault", - "text": "Good luck, have fun", - "room": "player" - } - - chatLineSpectator: - value: { - "type": "chatLine", - "username": "lovlas", - "text": "!eval", - "room": "spectator" - } - - opponentGoneTrue: - value: { - "type": "opponentGone", - "gone": true, - "claimWinInSeconds": 8 - } - - opponentGoneFalse: - value: { - "type": "opponentGone", - "gone": false - } - - gameStateResign: - value: { - "type": "gameState", - "moves": "e2e4 c7c5 f2f4 d7d6 g1f3 b8c6 f1c4 g8f6 d2d3 g7g6 e1g1 f8g7 b1c3", - "wtime": 7598040, - "btime": 8395220, - "winc": 10000, - "binc": 10000, - "status": "resign", - "winner": "black" - } + $ref: './examples/_index.yaml' + diff --git a/doc/specs/schemas/ArenaPerf.yaml b/doc/specs/schemas/ArenaPerf.yaml new file mode 100644 index 0000000..943f9bc --- /dev/null +++ b/doc/specs/schemas/ArenaPerf.yaml @@ -0,0 +1,14 @@ +type: object +properties: + key: + type: string + example: "blitz" + name: + type: string + example: "Blitz" + position: + type: integer + example: 1 + icon: + type: string + example: ")" diff --git a/doc/specs/schemas/ArenaPosition.yaml b/doc/specs/schemas/ArenaPosition.yaml new file mode 100644 index 0000000..dcdcad8 --- /dev/null +++ b/doc/specs/schemas/ArenaPosition.yaml @@ -0,0 +1,25 @@ +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" diff --git a/doc/specs/schemas/ArenaRatingObj.yaml b/doc/specs/schemas/ArenaRatingObj.yaml new file mode 100644 index 0000000..e3640b5 --- /dev/null +++ b/doc/specs/schemas/ArenaRatingObj.yaml @@ -0,0 +1,7 @@ +type: object +properties: + perf: + $ref: './PerfType.yaml' + rating: + type: integer + example: 1700 diff --git a/doc/specs/schemas/ArenaStatus.yaml b/doc/specs/schemas/ArenaStatus.yaml new file mode 100644 index 0000000..d54eaa7 --- /dev/null +++ b/doc/specs/schemas/ArenaStatus.yaml @@ -0,0 +1,8 @@ +type: integer +description: | + 10: created, 20: started, 30: finished +enum: + - 10 + - 20 + - 30 +example: 30 diff --git a/doc/specs/schemas/ArenaTournament.yaml b/doc/specs/schemas/ArenaTournament.yaml new file mode 100644 index 0000000..42a76e2 --- /dev/null +++ b/doc/specs/schemas/ArenaTournament.yaml @@ -0,0 +1,98 @@ +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: './Clock.yaml' + rated: + type: boolean + example: true + fullName: + type: string + example: "U1700 SuperBlitz Arena" + nbPlayers: + type: integer + example: 154 + variant: + $ref: './Variant.yaml' + startsAt: + type: integer + example: 1522803600000 + finishesAt: + type: integer + example: 1522807200000 + status: + $ref: './ArenaStatus.yaml' + perf: + $ref: './ArenaPerf.yaml' + secondsToStart: + type: integer + example: 576 + hasMaxRating: + type: boolean + example: true + maxRating: + $ref: './ArenaRatingObj.yaml' + minRating: + $ref: './ArenaRatingObj.yaml' + minRatedGames: + type: object + properties: + nb: + type: integer + example: 20 + perf: + $ref: './PerfType.yaml' + example: "blitz" + onlyTitled: + type: boolean + example: false + teamMember: + type: string + example: "coders" + private: + type: boolean + example: true + position: + $ref: './ArenaPosition.yaml' + 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: './Title.yaml' diff --git a/doc/specs/schemas/ArenaTournamentVariantIsKey.yaml b/doc/specs/schemas/ArenaTournamentVariantIsKey.yaml new file mode 100644 index 0000000..5d89ffd --- /dev/null +++ b/doc/specs/schemas/ArenaTournamentVariantIsKey.yaml @@ -0,0 +1,127 @@ +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 + } +} diff --git a/doc/specs/schemas/ArenaTournaments.yaml b/doc/specs/schemas/ArenaTournaments.yaml new file mode 100644 index 0000000..c05f042 --- /dev/null +++ b/doc/specs/schemas/ArenaTournaments.yaml @@ -0,0 +1,14 @@ +type: object +properties: + created: + type: array + items: + $ref: './ArenaTournament.yaml' + started: + type: array + items: + $ref: './ArenaTournament.yaml' + finished: + type: array + items: + $ref: './ArenaTournament.yaml' diff --git a/doc/specs/schemas/BroadcastForm.yaml b/doc/specs/schemas/BroadcastForm.yaml new file mode 100644 index 0000000..38ab987 --- /dev/null +++ b/doc/specs/schemas/BroadcastForm.yaml @@ -0,0 +1,45 @@ +type: object +properties: + name: + type: string + description: | + Name of the broadcast tournament. Length must be between 3 and 80 characters. + + Example: `Sinquefield Cup` + description: + type: string + description: | + Short description of the broadcast tournament. Length must be between 3 and 400 characters. + + Example: `An 11 round classical tournament featuring the 9 highest rated players in the world. Including Carlsen, Caruana, Ding, Aronian, Nakamura and more.` + 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. + + * `3` for normal + * `4` for high + * `5` for best + players: + description: | + Optional replace player names, ratings and titles. + + One line per player, formatted as such: + + `Original name; Replacement name; Optional replacement rating; Optional replacement title` + + Example: + + DrNykterstein;Magnus Carlsen;2863 + + AnishGiri;Anish Giri;2764;GM +required: + - name + - description + - autoLeaderboard diff --git a/doc/specs/schemas/BroadcastMyRound.yaml b/doc/specs/schemas/BroadcastMyRound.yaml new file mode 100644 index 0000000..2f28ce4 --- /dev/null +++ b/doc/specs/schemas/BroadcastMyRound.yaml @@ -0,0 +1,22 @@ +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 + }, +} + + diff --git a/doc/specs/schemas/BroadcastRound.yaml b/doc/specs/schemas/BroadcastRound.yaml new file mode 100644 index 0000000..cf65a85 --- /dev/null +++ b/doc/specs/schemas/BroadcastRound.yaml @@ -0,0 +1,41 @@ +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" + } + ] + } diff --git a/doc/specs/schemas/BroadcastTour.yaml b/doc/specs/schemas/BroadcastTour.yaml new file mode 100644 index 0000000..d8efc65 --- /dev/null +++ b/doc/specs/schemas/BroadcastTour.yaml @@ -0,0 +1,28 @@ +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 + } + ] + } + + diff --git a/doc/specs/schemas/BulkPairing.yaml b/doc/specs/schemas/BulkPairing.yaml new file mode 100644 index 0000000..6eeeb1e --- /dev/null +++ b/doc/specs/schemas/BulkPairing.yaml @@ -0,0 +1,30 @@ +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 +} diff --git a/doc/specs/schemas/ChallengeCancelJson.yaml b/doc/specs/schemas/ChallengeCancelJson.yaml new file mode 100644 index 0000000..e1a9829 --- /dev/null +++ b/doc/specs/schemas/ChallengeCancelJson.yaml @@ -0,0 +1,9 @@ +type: object +properties: + id: + type: string +example: { + "id": "VU0nyvsW" +} + + diff --git a/doc/specs/schemas/ChallengeCanceledEvent.yaml b/doc/specs/schemas/ChallengeCanceledEvent.yaml new file mode 100644 index 0000000..65a8ebd --- /dev/null +++ b/doc/specs/schemas/ChallengeCanceledEvent.yaml @@ -0,0 +1,7 @@ +type: object +properties: + type: + type: string + const: challengeCanceled + challenge: + $ref: './ChallengeJson.yaml' diff --git a/doc/specs/schemas/ChallengeCanceledJson.yaml b/doc/specs/schemas/ChallengeCanceledJson.yaml new file mode 100644 index 0000000..e1a9829 --- /dev/null +++ b/doc/specs/schemas/ChallengeCanceledJson.yaml @@ -0,0 +1,9 @@ +type: object +properties: + id: + type: string +example: { + "id": "VU0nyvsW" +} + + diff --git a/doc/specs/schemas/ChallengeDeclinedEvent.yaml b/doc/specs/schemas/ChallengeDeclinedEvent.yaml new file mode 100644 index 0000000..db005bf --- /dev/null +++ b/doc/specs/schemas/ChallengeDeclinedEvent.yaml @@ -0,0 +1,7 @@ +type: object +properties: + type: + type: string + const: challengeDeclined + challenge: + $ref: './ChallengeCanceledJson.yaml' diff --git a/doc/specs/schemas/ChallengeEvent.yaml b/doc/specs/schemas/ChallengeEvent.yaml new file mode 100644 index 0000000..a92edb8 --- /dev/null +++ b/doc/specs/schemas/ChallengeEvent.yaml @@ -0,0 +1,7 @@ +type: object +properties: + type: + type: string + const: challenge + challenge: + $ref: './ChallengeJson.yaml' diff --git a/doc/specs/schemas/ChallengeJson.yaml b/doc/specs/schemas/ChallengeJson.yaml new file mode 100644 index 0000000..1064a34 --- /dev/null +++ b/doc/specs/schemas/ChallengeJson.yaml @@ -0,0 +1,130 @@ +type: object +properties: + id: + type: string + url: + type: string + status: + type: string + enum: + - created + - offline + - canceled + - declined + - accepted + challenger: + $ref: './ChallengeUser.yaml' + destUser: + oneOf: + - $ref: './ChallengeUser.yaml' + - type: 'null' + variant: + $ref: './Variant.yaml' + rated: + type: boolean + speed: + $ref: './Speed.yaml' + 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" +} diff --git a/doc/specs/schemas/ChallengeOpenJson.yaml b/doc/specs/schemas/ChallengeOpenJson.yaml new file mode 100644 index 0000000..8df1832 --- /dev/null +++ b/doc/specs/schemas/ChallengeOpenJson.yaml @@ -0,0 +1,42 @@ +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" +} diff --git a/doc/specs/schemas/ChallengeUser.yaml b/doc/specs/schemas/ChallengeUser.yaml new file mode 100644 index 0000000..f3c2df4 --- /dev/null +++ b/doc/specs/schemas/ChallengeUser.yaml @@ -0,0 +1,9 @@ +allOf: + - $ref: './LightUser.yaml' +properties: + rating: + type: number + provisional: + type: boolean + online: + type: boolean diff --git a/doc/specs/schemas/ChatLineEvent.yaml b/doc/specs/schemas/ChatLineEvent.yaml new file mode 100644 index 0000000..bf2b717 --- /dev/null +++ b/doc/specs/schemas/ChatLineEvent.yaml @@ -0,0 +1,19 @@ +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 diff --git a/doc/specs/schemas/Clock.yaml b/doc/specs/schemas/Clock.yaml new file mode 100644 index 0000000..458c201 --- /dev/null +++ b/doc/specs/schemas/Clock.yaml @@ -0,0 +1,6 @@ +type: object +properties: + limit: + type: integer + increment: + type: integer diff --git a/doc/specs/schemas/Count.yaml b/doc/specs/schemas/Count.yaml new file mode 100644 index 0000000..5c9c75a --- /dev/null +++ b/doc/specs/schemas/Count.yaml @@ -0,0 +1,41 @@ +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 diff --git a/doc/specs/schemas/Crosstable.yaml b/doc/specs/schemas/Crosstable.yaml new file mode 100644 index 0000000..ec0978d --- /dev/null +++ b/doc/specs/schemas/Crosstable.yaml @@ -0,0 +1,14 @@ +example: { + "users": { + "neio": 201.5, + "thibault": 144.5 + }, + "nbGames": 346, + "matchup": { + "users": { + "neio": 44, + "thibault": 43 + }, + "nbGames": 87 + } + } diff --git a/doc/specs/schemas/Error.yaml b/doc/specs/schemas/Error.yaml new file mode 100644 index 0000000..8339c87 --- /dev/null +++ b/doc/specs/schemas/Error.yaml @@ -0,0 +1,6 @@ +properties: + error: + type: string + description: The cause of the error. +example: + error: "This request is invalid because [...]" diff --git a/doc/specs/schemas/ExternalEngine.yaml b/doc/specs/schemas/ExternalEngine.yaml new file mode 100644 index 0000000..4b2af31 --- /dev/null +++ b/doc/specs/schemas/ExternalEngine.yaml @@ -0,0 +1,64 @@ +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 + [*request* analysis](#tag/External-engine/operation/apiExternalEngineAnalyse) + from this external engine. + 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: './UciVariant.yaml' + providerData: + type: string + description: | + Arbitrary data that the engine provider can use for identification + or bookkeeping. + + Users can read this information, but updating it requires knowing + or changing the `providerSecret`. +required: + - id + - clientSecret + - userId + - name + - maxThreads + - maxHash + - defaultDepth + - variants diff --git a/doc/specs/schemas/ExternalEngineRegistration.yaml b/doc/specs/schemas/ExternalEngineRegistration.yaml new file mode 100644 index 0000000..3b7383f --- /dev/null +++ b/doc/specs/schemas/ExternalEngineRegistration.yaml @@ -0,0 +1,69 @@ +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: './UciVariant.yaml' + #officialStockfish: + # type: boolean + # description: | + # Promises that the engine is a recent official Stockfish release. + # Can be considered for cloud evaluation. + # required: false + providerSecret: + type: string + description: | + A random token that can be used to + [wait for analysis requests](#tag/External-engine/operation/apiExternalEngineAcquire) + and provide analysis. + + The engine provider should securely generate a random string. + + The token will not be readable again, even by the user. + + The analysis provider can register multiple engines with the same + token, even for different users, and wait for analysis requests + from any of them. In this case, the request must not be made via + CORS, so that the token is not revealed to any of the users. + example: Dee3uwieZei9ahpaici9bee2yahsai0K + minLength: 16 + maxLength: 1024 + providerData: + type: string + description: | + Arbitrary data that the engine provider can use for identification + or bookkeeping. + + Users can read this information, but updating it requires knowing + or changing the `providerSecret`. +required: + - name + - maxThreads + - maxHash + - defaultDepth + - providerSecret diff --git a/doc/specs/schemas/ExternalEngineWork.yaml b/doc/specs/schemas/ExternalEngineWork.yaml new file mode 100644 index 0000000..09177e5 --- /dev/null +++ b/doc/specs/schemas/ExternalEngineWork.yaml @@ -0,0 +1,50 @@ +type: object +properties: + sessionId: + type: string + description: | + Arbitary string that identifies the analysis session. + Providers may wish to clear the hash table between sessions. + 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 + `defaultDepth`). + example: false + multiPv: + type: integer + minimum: 1 + maximum: 5 + description: Requested number of principal variations. + example: 1 + variant: + $ref: './UciVariant.yaml' + 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 diff --git a/doc/specs/schemas/FromPositionFEN.yaml b/doc/specs/schemas/FromPositionFEN.yaml new file mode 100644 index 0000000..0e4655a --- /dev/null +++ b/doc/specs/schemas/FromPositionFEN.yaml @@ -0,0 +1,3 @@ +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" diff --git a/doc/specs/schemas/GameChat.yaml b/doc/specs/schemas/GameChat.yaml new file mode 100644 index 0000000..4cbc616 --- /dev/null +++ b/doc/specs/schemas/GameChat.yaml @@ -0,0 +1,12 @@ +example: [{ + "text": "Takeback sent", + "user": "lichess" + }, + { + "text": "Takeback accepted", + "user": "lichess" + }, + { + "text": "Good game, well played", + "user": "thibault" + }] diff --git a/doc/specs/schemas/GameEventInfo.yaml b/doc/specs/schemas/GameEventInfo.yaml new file mode 100644 index 0000000..fb606f2 --- /dev/null +++ b/doc/specs/schemas/GameEventInfo.yaml @@ -0,0 +1,37 @@ +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: './GameStatus.yaml' + winner: + type: string + enum: [white, black] + compat: + type: object + properties: + bot: + type: boolean + board: + type: boolean diff --git a/doc/specs/schemas/GameEventPlayer.yaml b/doc/specs/schemas/GameEventPlayer.yaml new file mode 100644 index 0000000..d78247e --- /dev/null +++ b/doc/specs/schemas/GameEventPlayer.yaml @@ -0,0 +1,14 @@ +type: object +properties: + aiLevel: + type: number + id: + type: string + name: + type: string + title: + type: [string, 'null'] + rating: + type: number + provisional: + type: boolean diff --git a/doc/specs/schemas/GameFinishEvent.yaml b/doc/specs/schemas/GameFinishEvent.yaml new file mode 100644 index 0000000..a82faf2 --- /dev/null +++ b/doc/specs/schemas/GameFinishEvent.yaml @@ -0,0 +1,7 @@ +type: object +properties: + type: + type: string + const: gameFinish + game: + $ref: './GameEventInfo.yaml' diff --git a/doc/specs/schemas/GameFullEvent.yaml b/doc/specs/schemas/GameFullEvent.yaml new file mode 100644 index 0000000..fffbf1e --- /dev/null +++ b/doc/specs/schemas/GameFullEvent.yaml @@ -0,0 +1,50 @@ +type: object +properties: + type: + type: string + const: gameFull + id: + type: string + variant: + $ref: './Variant.yaml' + clock: + oneOf: + - $ref: './Clock.yaml' + - type: 'null' + speed: + $ref: './Speed.yaml' + 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: './GameEventPlayer.yaml' + black: + $ref: './GameEventPlayer.yaml' + initialFen: + type: string + default: "startpos" + state: + $ref: './GameStateEvent.yaml' + tournamentId: + type: string +required: + - type + - id + - variant + - clock + - speed + - perf + - rated + - createdAt + - white + - black + - initialFen + - state diff --git a/doc/specs/schemas/GameJson.yaml b/doc/specs/schemas/GameJson.yaml new file mode 100644 index 0000000..85c5d44 --- /dev/null +++ b/doc/specs/schemas/GameJson.yaml @@ -0,0 +1,154 @@ +type: object +properties: + id: + type: string + rated: + type: boolean + variant: + $ref: './VariantKey.yaml' + speed: + $ref: './Speed.yaml' + perf: + type: string + createdAt: + type: number + format: int64 + lastMoveAt: + type: number + format: int64 + status: + $ref: './GameStatus.yaml' + players: + type: object + properties: + white: + $ref: './GameUser.yaml' + black: + $ref: './GameUser.yaml' + 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 + } +} diff --git a/doc/specs/schemas/GamePgn.yaml b/doc/specs/schemas/GamePgn.yaml new file mode 100644 index 0000000..27b8d85 --- /dev/null +++ b/doc/specs/schemas/GamePgn.yaml @@ -0,0 +1,22 @@ +example: | + [Event "Rated Blitz game"] + [Site "https://lichess.org/fY44h4OY"] + [Date "2018.03.29"] + [Round "-"] + [White "pveldman"] + [Black "thibault"] + [Result "1-0"] + [UTCDate "2018.03.29"] + [UTCTime "01:38:15"] + [WhiteElo "1610"] + [BlackElo "1601"] + [WhiteRatingDiff "+10"] + [BlackRatingDiff "-10"] + [Variant "Standard"] + [TimeControl "180+0"] + [ECO "C62"] + [Opening "Ruy Lopez: Steinitz Defense"] + [Termination "Normal"] + [Event "U1700 SuperBlitz Arena"] + + 1. 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 diff --git a/doc/specs/schemas/GameStartEvent.yaml b/doc/specs/schemas/GameStartEvent.yaml new file mode 100644 index 0000000..ba3a5b0 --- /dev/null +++ b/doc/specs/schemas/GameStartEvent.yaml @@ -0,0 +1,7 @@ +type: object +properties: + type: + type: string + const: gameStart + game: + $ref: './GameEventInfo.yaml' diff --git a/doc/specs/schemas/GameStateEvent.yaml b/doc/specs/schemas/GameStateEvent.yaml new file mode 100644 index 0000000..0de3d50 --- /dev/null +++ b/doc/specs/schemas/GameStateEvent.yaml @@ -0,0 +1,45 @@ +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: './GameStatus.yaml' + 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 diff --git a/doc/specs/schemas/GameStatus.yaml b/doc/specs/schemas/GameStatus.yaml new file mode 100644 index 0000000..b4acf91 --- /dev/null +++ b/doc/specs/schemas/GameStatus.yaml @@ -0,0 +1,18 @@ +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 + + diff --git a/doc/specs/schemas/GameStream.yaml b/doc/specs/schemas/GameStream.yaml new file mode 100644 index 0000000..8156527 --- /dev/null +++ b/doc/specs/schemas/GameStream.yaml @@ -0,0 +1,27 @@ +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 + } + } + } +] diff --git a/doc/specs/schemas/GameUser.yaml b/doc/specs/schemas/GameUser.yaml new file mode 100644 index 0000000..3fc43b6 --- /dev/null +++ b/doc/specs/schemas/GameUser.yaml @@ -0,0 +1,28 @@ +type: object +properties: + user: + $ref: "./LightUser.yaml" + 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 diff --git a/doc/specs/schemas/Leaderboard.yaml b/doc/specs/schemas/Leaderboard.yaml new file mode 100644 index 0000000..7e87a99 --- /dev/null +++ b/doc/specs/schemas/Leaderboard.yaml @@ -0,0 +1,40 @@ +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" + }, + ] +} diff --git a/doc/specs/schemas/LightUser.yaml b/doc/specs/schemas/LightUser.yaml new file mode 100644 index 0000000..7ebc459 --- /dev/null +++ b/doc/specs/schemas/LightUser.yaml @@ -0,0 +1,16 @@ +type: object +properties: + id: + type: string + example: "chess-network" + name: + type: string + example: "Chess-Network" + title: + $ref: './Title.yaml' + patron: + type: boolean + example: true +required: + - id + - name diff --git a/doc/specs/schemas/LightUserOnline.yaml b/doc/specs/schemas/LightUserOnline.yaml new file mode 100644 index 0000000..cfe8bca --- /dev/null +++ b/doc/specs/schemas/LightUserOnline.yaml @@ -0,0 +1,5 @@ +allOf: + - $ref: './LightUser.yaml' + - properties: + online: + type: boolean diff --git a/doc/specs/schemas/MasterGamePgn.yaml b/doc/specs/schemas/MasterGamePgn.yaml new file mode 100644 index 0000000..5c2e340 --- /dev/null +++ b/doc/specs/schemas/MasterGamePgn.yaml @@ -0,0 +1,12 @@ +example: | + [Event "Wch Blitz"] + [Site "Astana"] + [Date "2012.07.10"] + [Round "23"] + [White "Carlsen, Magnus"] + [Black "Chadaev, Nikolay"] + [Result "1-0"] + [WhiteElo "2837"] + [BlackElo "2580"] + + 1. 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 diff --git a/doc/specs/schemas/Move.yaml b/doc/specs/schemas/Move.yaml new file mode 100644 index 0000000..cff1a28 --- /dev/null +++ b/doc/specs/schemas/Move.yaml @@ -0,0 +1,41 @@ +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 + 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 diff --git a/doc/specs/schemas/MoveStream.yaml b/doc/specs/schemas/MoveStream.yaml new file mode 100644 index 0000000..6382f3e --- /dev/null +++ b/doc/specs/schemas/MoveStream.yaml @@ -0,0 +1,50 @@ +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 + } +] diff --git a/doc/specs/schemas/NotFound.yaml b/doc/specs/schemas/NotFound.yaml new file mode 100644 index 0000000..e54b2f5 --- /dev/null +++ b/doc/specs/schemas/NotFound.yaml @@ -0,0 +1,5 @@ +properties: + error: + type: string +example: + error: "Not found." diff --git a/doc/specs/schemas/OAuthError.yaml b/doc/specs/schemas/OAuthError.yaml new file mode 100644 index 0000000..a1fd0cf --- /dev/null +++ b/doc/specs/schemas/OAuthError.yaml @@ -0,0 +1,10 @@ +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" diff --git a/doc/specs/schemas/Ok.yaml b/doc/specs/schemas/Ok.yaml new file mode 100644 index 0000000..d36f796 --- /dev/null +++ b/doc/specs/schemas/Ok.yaml @@ -0,0 +1,5 @@ +properties: + ok: + type: boolean +example: + ok: true diff --git a/doc/specs/schemas/OpeningExplorerJson.yaml b/doc/specs/schemas/OpeningExplorerJson.yaml new file mode 100644 index 0000000..934ce9d --- /dev/null +++ b/doc/specs/schemas/OpeningExplorerJson.yaml @@ -0,0 +1,89 @@ +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 + } + ], +} diff --git a/doc/specs/schemas/OpeningExplorerPlayerJson.yaml b/doc/specs/schemas/OpeningExplorerPlayerJson.yaml new file mode 100644 index 0000000..b0fc861 --- /dev/null +++ b/doc/specs/schemas/OpeningExplorerPlayerJson.yaml @@ -0,0 +1,121 @@ +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 +} diff --git a/doc/specs/schemas/OpponentGone.yaml b/doc/specs/schemas/OpponentGone.yaml new file mode 100644 index 0000000..a1686ab --- /dev/null +++ b/doc/specs/schemas/OpponentGone.yaml @@ -0,0 +1,12 @@ +type: object +properties: + type: + type: string + const: opponentGone + gone: + type: boolean + claimWinInSeconds: + type: number +required: + - type + - gone diff --git a/doc/specs/schemas/Perf.yaml b/doc/specs/schemas/Perf.yaml new file mode 100644 index 0000000..ed9fadb --- /dev/null +++ b/doc/specs/schemas/Perf.yaml @@ -0,0 +1,16 @@ +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 diff --git a/doc/specs/schemas/PerfStat.yaml b/doc/specs/schemas/PerfStat.yaml new file mode 100644 index 0000000..26cc8bc --- /dev/null +++ b/doc/specs/schemas/PerfStat.yaml @@ -0,0 +1,135 @@ +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" + } + } +} diff --git a/doc/specs/schemas/PerfType.yaml b/doc/specs/schemas/PerfType.yaml new file mode 100644 index 0000000..7d14d86 --- /dev/null +++ b/doc/specs/schemas/PerfType.yaml @@ -0,0 +1,16 @@ +type: string +enum: + - ultraBullet + - bullet + - blitz + - rapid + - classical + - correspondence + - chess960 + - crazyhouse + - antichess + - atomic + - horde + - kingOfTheHill + - racingKings + - threeCheck diff --git a/doc/specs/schemas/Perfs.yaml b/doc/specs/schemas/Perfs.yaml new file mode 100644 index 0000000..b3c4436 --- /dev/null +++ b/doc/specs/schemas/Perfs.yaml @@ -0,0 +1,32 @@ +type: object +properties: + chess960: + $ref: './Perf.yaml' + atomic: + $ref: './Perf.yaml' + racingKings: + $ref: './Perf.yaml' + ultraBullet: + $ref: './Perf.yaml' + blitz: + $ref: './Perf.yaml' + kingOfTheHill: + $ref: './Perf.yaml' + bullet: + $ref: './Perf.yaml' + correspondence: + $ref: './Perf.yaml' + horde: + $ref: './Perf.yaml' + puzzle: + $ref: './Perf.yaml' + classical: + $ref: './Perf.yaml' + rapid: + $ref: './Perf.yaml' + storm: + $ref: './PuzzleModePerf.yaml' + racer: + $ref: './PuzzleModePerf.yaml' + streak: + $ref: './PuzzleModePerf.yaml' diff --git a/doc/specs/schemas/PlayTime.yaml b/doc/specs/schemas/PlayTime.yaml new file mode 100644 index 0000000..d3a841a --- /dev/null +++ b/doc/specs/schemas/PlayTime.yaml @@ -0,0 +1,8 @@ +type: object +properties: + total: + type: integer + example: 3296897 + tv: + type: integer + example: 12134 diff --git a/doc/specs/schemas/Profile.yaml b/doc/specs/schemas/Profile.yaml new file mode 100644 index 0000000..55acc79 --- /dev/null +++ b/doc/specs/schemas/Profile.yaml @@ -0,0 +1,28 @@ +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 + uscfRating: + type: integer + example: 1500 + ecfRating: + type: integer + example: 1500 + links: + type: string + example: "github.com/ornicar\r\ntwitter.com/ornicar" diff --git a/doc/specs/schemas/PuzzleAndGame.yaml b/doc/specs/schemas/PuzzleAndGame.yaml new file mode 100644 index 0000000..2faf3ad --- /dev/null +++ b/doc/specs/schemas/PuzzleAndGame.yaml @@ -0,0 +1,43 @@ +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" + ] + } + } + + diff --git a/doc/specs/schemas/PuzzleDashboardJson.yaml b/doc/specs/schemas/PuzzleDashboardJson.yaml new file mode 100644 index 0000000..af08b82 --- /dev/null +++ b/doc/specs/schemas/PuzzleDashboardJson.yaml @@ -0,0 +1,32 @@ +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" + } + } +} diff --git a/doc/specs/schemas/PuzzleModePerf.yaml b/doc/specs/schemas/PuzzleModePerf.yaml new file mode 100644 index 0000000..7d65c4d --- /dev/null +++ b/doc/specs/schemas/PuzzleModePerf.yaml @@ -0,0 +1,8 @@ +type: object +properties: + runs: + type: integer + example: 44 + score: + type: integer + example: 61 diff --git a/doc/specs/schemas/PuzzleRaceJson.yaml b/doc/specs/schemas/PuzzleRaceJson.yaml new file mode 100644 index 0000000..e3b8efd --- /dev/null +++ b/doc/specs/schemas/PuzzleRaceJson.yaml @@ -0,0 +1,4 @@ +example: { + "id": "Kj1t0", + "url": "https://lichess.org/racer/Kj1t0" +} diff --git a/doc/specs/schemas/PuzzleRoundJson.yaml b/doc/specs/schemas/PuzzleRoundJson.yaml new file mode 100644 index 0000000..28b0e10 --- /dev/null +++ b/doc/specs/schemas/PuzzleRoundJson.yaml @@ -0,0 +1,18 @@ +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" ] + } diff --git a/doc/specs/schemas/RatingHistory.yaml b/doc/specs/schemas/RatingHistory.yaml new file mode 100644 index 0000000..eff2f84 --- /dev/null +++ b/doc/specs/schemas/RatingHistory.yaml @@ -0,0 +1 @@ +example: [{"name": "Bullet","points":[[2011,0,8,1472],[2011,0,9,1332],[2011,8,12,1314]]},{"name": "Blitz","points":[[2011,7,29,1332]]}] diff --git a/doc/specs/schemas/Simul.yaml b/doc/specs/schemas/Simul.yaml new file mode 100644 index 0000000..4be9445 --- /dev/null +++ b/doc/specs/schemas/Simul.yaml @@ -0,0 +1,27 @@ +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" + } + ] +} diff --git a/doc/specs/schemas/Speed.yaml b/doc/specs/schemas/Speed.yaml new file mode 100644 index 0000000..4d2bb52 --- /dev/null +++ b/doc/specs/schemas/Speed.yaml @@ -0,0 +1,8 @@ +type: string +enum: + - ultraBullet + - bullet + - blitz + - rapid + - classical + - correspondence diff --git a/doc/specs/schemas/StormDashboardJson.yaml b/doc/specs/schemas/StormDashboardJson.yaml new file mode 100644 index 0000000..7a25553 --- /dev/null +++ b/doc/specs/schemas/StormDashboardJson.yaml @@ -0,0 +1,40 @@ +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 + }, + ] +} diff --git a/doc/specs/schemas/StudyImportPgnChapters.yaml b/doc/specs/schemas/StudyImportPgnChapters.yaml new file mode 100644 index 0000000..5dfbc32 --- /dev/null +++ b/doc/specs/schemas/StudyImportPgnChapters.yaml @@ -0,0 +1,6 @@ +example: { + "chapters": [{ + "id": "WTvnkWAL", + "name": "Game 2" + }], +} diff --git a/doc/specs/schemas/StudyMetadata.yaml b/doc/specs/schemas/StudyMetadata.yaml new file mode 100644 index 0000000..101ff05 --- /dev/null +++ b/doc/specs/schemas/StudyMetadata.yaml @@ -0,0 +1,6 @@ +example: { + "id": "WTvnkWAL", + "name": "Guess the move", + "createdAt": 1463756350225, + "updatedAt": 1469965025205 +} diff --git a/doc/specs/schemas/StudyPgn.yaml b/doc/specs/schemas/StudyPgn.yaml new file mode 100644 index 0000000..0c6e2ae --- /dev/null +++ b/doc/specs/schemas/StudyPgn.yaml @@ -0,0 +1,13 @@ +example: | + [Event "All about the Sicilian Defense: Dragon Variation"] + [Site "https://lichess.org/study/8c8bmUfy/qwnXMwVC"] + [Result "*"] + [UTCDate "2017.06.25"] + [UTCTime "10:12:04"] + [Variant "Standard"] + [ECO "B76"] + [Opening "Sicilian Defense: Dragon Variation, Yugoslav Attack, Panov Variation"] + [Annotator "https://lichess.org/@/Francesco_Super"] + + { 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. } + 1. 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 * diff --git a/doc/specs/schemas/SwissTournament.yaml b/doc/specs/schemas/SwissTournament.yaml new file mode 100644 index 0000000..b67f877 --- /dev/null +++ b/doc/specs/schemas/SwissTournament.yaml @@ -0,0 +1,32 @@ +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 + } +} diff --git a/doc/specs/schemas/SwissUnauthorisedEdit.yaml b/doc/specs/schemas/SwissUnauthorisedEdit.yaml new file mode 100644 index 0000000..f43a000 --- /dev/null +++ b/doc/specs/schemas/SwissUnauthorisedEdit.yaml @@ -0,0 +1,5 @@ +properties: + error: + type: string +example: + error: "This user cannot edit this swiss" diff --git a/doc/specs/schemas/TablebaseJson.yaml b/doc/specs/schemas/TablebaseJson.yaml new file mode 100644 index 0000000..3f746da --- /dev/null +++ b/doc/specs/schemas/TablebaseJson.yaml @@ -0,0 +1,78 @@ +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 + the decisive result. + + `maybe-win` and `maybe-loss` means exact result is unknown due to + [DTZ rounding](https://syzygy-tables.info/metrics#dtz), i.e., the + win or loss could also be prevented by the 50-move rule if + the user has deviated from the tablebase recommendation since the + last pawn move or capture. + dtz: + type: integer + description: | + [DTZ50'' with rounding](https://syzygy-tables.info/metrics#dtz) or null if unknown + precise_dtz: + type: integer + description: | + DTZ50'' (only if guaranteed to be not rounded) or null if unknown + 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: './Move.yaml' +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" + } + ] + } diff --git a/doc/specs/schemas/Team.yaml b/doc/specs/schemas/Team.yaml new file mode 100644 index 0000000..5a7b83f --- /dev/null +++ b/doc/specs/schemas/Team.yaml @@ -0,0 +1,21 @@ +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: './LightUser.yaml' + nbMembers: + type: integer + example: 3129 diff --git a/doc/specs/schemas/TeamPaginatorJson.yaml b/doc/specs/schemas/TeamPaginatorJson.yaml new file mode 100644 index 0000000..3509992 --- /dev/null +++ b/doc/specs/schemas/TeamPaginatorJson.yaml @@ -0,0 +1,24 @@ +type: object +properties: + currentPage: + type: number + example: 4 + maxPerPage: + type: number + example: 15 + currentPageResults: + type: array + items: + $ref: './Team.yaml' + nbResults: + type: number + example: 205194 + previousPage: + type: [number, 'null'] + example: 3 + nextPage: + type: [number, 'null'] + example: 5 + nbPages: + type: number + example: 13680 diff --git a/doc/specs/schemas/TeamRequest.yaml b/doc/specs/schemas/TeamRequest.yaml new file mode 100644 index 0000000..e433263 --- /dev/null +++ b/doc/specs/schemas/TeamRequest.yaml @@ -0,0 +1,14 @@ +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!" diff --git a/doc/specs/schemas/TeamRequestWithUser.yaml b/doc/specs/schemas/TeamRequestWithUser.yaml new file mode 100644 index 0000000..2271de6 --- /dev/null +++ b/doc/specs/schemas/TeamRequestWithUser.yaml @@ -0,0 +1,6 @@ +type: object +properties: + request: + $ref: './TeamRequest.yaml' + user: + $ref: './User.yaml' diff --git a/doc/specs/schemas/Timeline.yaml b/doc/specs/schemas/Timeline.yaml new file mode 100644 index 0000000..76699fc --- /dev/null +++ b/doc/specs/schemas/Timeline.yaml @@ -0,0 +1,154 @@ +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 + } + } +} diff --git a/doc/specs/schemas/Title.yaml b/doc/specs/schemas/Title.yaml new file mode 100644 index 0000000..b201ad6 --- /dev/null +++ b/doc/specs/schemas/Title.yaml @@ -0,0 +1,3 @@ +type: string +enum: [GM, WGM, IM, WIM, FM, WFM, NM, CM, WCM, WNM, LM, BOT] +example: NM diff --git a/doc/specs/schemas/Top10s.yaml b/doc/specs/schemas/Top10s.yaml new file mode 100644 index 0000000..a35ec26 --- /dev/null +++ b/doc/specs/schemas/Top10s.yaml @@ -0,0 +1,52 @@ +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": [] +} diff --git a/doc/specs/schemas/UciVariant.yaml b/doc/specs/schemas/UciVariant.yaml new file mode 100644 index 0000000..f674dd5 --- /dev/null +++ b/doc/specs/schemas/UciVariant.yaml @@ -0,0 +1,12 @@ +type: string +enum: + - chess + - crazyhouse + - antichess + - atomic + - horde + - kingofthehill + - racingkings + - 3check +example: chess +default: chess diff --git a/doc/specs/schemas/User.yaml b/doc/specs/schemas/User.yaml new file mode 100644 index 0000000..626e4d5 --- /dev/null +++ b/doc/specs/schemas/User.yaml @@ -0,0 +1,36 @@ +type: object +properties: + id: + type: string + example: georges + username: + type: string + example: Georges + perfs: + $ref: './Perfs.yaml' + createdAt: + type: integer + format: int64 + example: 1290415680000 + disabled: + type: boolean + example: false + tosViolation: + type: boolean + example: false + profile: + $ref: './Profile.yaml' + seenAt: + type: integer + format: int64 + example: 1522636452014 + patron: + type: boolean + example: true + verified: + type: boolean + example: true + playTime: + $ref: './PlayTime.yaml' + title: + $ref: './Title.yaml' diff --git a/doc/specs/schemas/UserExtended.yaml b/doc/specs/schemas/UserExtended.yaml new file mode 100644 index 0000000..0dde892 --- /dev/null +++ b/doc/specs/schemas/UserExtended.yaml @@ -0,0 +1,37 @@ +allOf: + - $ref: './User.yaml' + - properties: + url: + type: string + format: uri + example: https://lichess.org/@/georges + playing: + type: string + format: uri + example: https://lichess.org/yqfLYJ5E/black + count: + $ref: './Count.yaml' + 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 + following: + type: boolean + example: false + blocking: + type: boolean + example: false + followsYou: + type: boolean + example: false diff --git a/doc/specs/schemas/UserNote.yaml b/doc/specs/schemas/UserNote.yaml new file mode 100644 index 0000000..a3b366e --- /dev/null +++ b/doc/specs/schemas/UserNote.yaml @@ -0,0 +1,13 @@ +type: object +properties: + from: + $ref: './LightUser.yaml' + to: + $ref: './LightUser.yaml' + text: + type: string + example: "This is a note" + date: + type: integer + format: int64 + example: 1290415680000 diff --git a/doc/specs/schemas/UserPreferences.yaml b/doc/specs/schemas/UserPreferences.yaml new file mode 100644 index 0000000..327ee1b --- /dev/null +++ b/doc/specs/schemas/UserPreferences.yaml @@ -0,0 +1,192 @@ +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 diff --git a/doc/specs/schemas/Variant.yaml b/doc/specs/schemas/Variant.yaml new file mode 100644 index 0000000..0678ac4 --- /dev/null +++ b/doc/specs/schemas/Variant.yaml @@ -0,0 +1,8 @@ +type: object +properties: + key: + $ref: './VariantKey.yaml' + name: + type: string + short: + type: string diff --git a/doc/specs/schemas/VariantKey.yaml b/doc/specs/schemas/VariantKey.yaml new file mode 100644 index 0000000..9aee340 --- /dev/null +++ b/doc/specs/schemas/VariantKey.yaml @@ -0,0 +1,14 @@ +type: string +enum: + - standard + - chess960 + - crazyhouse + - antichess + - atomic + - horde + - kingOfTheHill + - racingKings + - threeCheck + - fromPosition +example: standard +default: standard diff --git a/doc/specs/schemas/_index.yaml b/doc/specs/schemas/_index.yaml new file mode 100644 index 0000000..663d2a3 --- /dev/null +++ b/doc/specs/schemas/_index.yaml @@ -0,0 +1,260 @@ +VariantKey: + $ref: './VariantKey.yaml' + +Variant: + $ref: './Variant.yaml' + +UciVariant: + $ref: './UciVariant.yaml' + +Speed: + $ref: './Speed.yaml' + +PerfType: + $ref: './PerfType.yaml' + +Clock: + $ref: './Clock.yaml' + +GameStatus: + $ref: './GameStatus.yaml' + +FromPositionFEN: + $ref: './FromPositionFEN.yaml' + +ChallengeUser: + $ref: './ChallengeUser.yaml' + +ChallengeJson: + $ref: './ChallengeJson.yaml' + +ChallengeCanceledJson: + $ref: './ChallengeCanceledJson.yaml' + +ChallengeOpenJson: + $ref: './ChallengeOpenJson.yaml' + +BulkPairing: + $ref: './BulkPairing.yaml' + +GameUser: + $ref: './GameUser.yaml' + +GameJson: + $ref: './GameJson.yaml' + +GamePgn: + $ref: './GamePgn.yaml' + +MasterGamePgn: + $ref: './MasterGamePgn.yaml' + +StudyPgn: + $ref: './StudyPgn.yaml' + +StudyMetadata: + $ref: './StudyMetadata.yaml' + +StudyImportPgnChapters: + $ref: './StudyImportPgnChapters.yaml' + +Title: + $ref: './Title.yaml' + +LightUser: + $ref: './LightUser.yaml' + +LightUserOnline: + $ref: './LightUserOnline.yaml' + +Perf: + $ref: './Perf.yaml' + +PuzzleModePerf: + $ref: './PuzzleModePerf.yaml' + +Perfs: + $ref: './Perfs.yaml' + +UserNote: + $ref: './UserNote.yaml' + +PlayTime: + $ref: './PlayTime.yaml' + +Profile: + $ref: './Profile.yaml' + +Count: + $ref: './Count.yaml' + +User: + $ref: './User.yaml' + +UserExtended: + $ref: './UserExtended.yaml' + +Crosstable: + $ref: './Crosstable.yaml' + +GameChat: + $ref: './GameChat.yaml' + +PuzzleAndGame: + $ref: './PuzzleAndGame.yaml' + +PuzzleRoundJson: + $ref: './PuzzleRoundJson.yaml' + +PuzzleDashboardJson: + $ref: './PuzzleDashboardJson.yaml' + +PuzzleRaceJson: + $ref: './PuzzleRaceJson.yaml' + +StormDashboardJson: + $ref: './StormDashboardJson.yaml' + +RatingHistory: + $ref: './RatingHistory.yaml' + +PerfStat: + $ref: './PerfStat.yaml' + +Top10s: + $ref: './Top10s.yaml' + +Leaderboard: + $ref: './Leaderboard.yaml' + +UserPreferences: + $ref: './UserPreferences.yaml' + +ArenaTournaments: + $ref: './ArenaTournaments.yaml' + +ArenaStatus: + $ref: './ArenaStatus.yaml' + +ArenaPerf: + $ref: './ArenaPerf.yaml' + +ArenaRatingObj: + $ref: './ArenaRatingObj.yaml' + +ArenaPosition: + $ref: './ArenaPosition.yaml' + +ArenaTournament: + $ref: './ArenaTournament.yaml' + +ArenaTournamentVariantIsKey: + $ref: './ArenaTournamentVariantIsKey.yaml' + +SwissTournament: + $ref: './SwissTournament.yaml' + +Simul: + $ref: './Simul.yaml' + +BroadcastForm: + $ref: './BroadcastForm.yaml' + +BroadcastTour: + $ref: './BroadcastTour.yaml' + +BroadcastRound: + $ref: './BroadcastRound.yaml' + +BroadcastMyRound: + $ref: './BroadcastMyRound.yaml' + +OpeningExplorerJson: + $ref: './OpeningExplorerJson.yaml' + +OpeningExplorerPlayerJson: + $ref: './OpeningExplorerPlayerJson.yaml' + +TablebaseJson: + $ref: './TablebaseJson.yaml' + +Move: + $ref: './Move.yaml' + +Team: + $ref: './Team.yaml' + +TeamPaginatorJson: + $ref: './TeamPaginatorJson.yaml' + +TeamRequest: + $ref: './TeamRequest.yaml' + +TeamRequestWithUser: + $ref: './TeamRequestWithUser.yaml' + +GameEventPlayer: + $ref: './GameEventPlayer.yaml' + +GameFullEvent: + $ref: './GameFullEvent.yaml' + +GameStateEvent: + $ref: './GameStateEvent.yaml' + +ChatLineEvent: + $ref: './ChatLineEvent.yaml' + +OpponentGone: + $ref: './OpponentGone.yaml' + +GameEventInfo: + $ref: './GameEventInfo.yaml' + +GameStartEvent: + $ref: './GameStartEvent.yaml' + +GameFinishEvent: + $ref: './GameFinishEvent.yaml' + +ChallengeEvent: + $ref: './ChallengeEvent.yaml' + +ChallengeCanceledEvent: + $ref: './ChallengeCanceledEvent.yaml' + +ChallengeDeclinedEvent: + $ref: './ChallengeDeclinedEvent.yaml' + +Ok: + $ref: './Ok.yaml' + +Error: + $ref: './Error.yaml' + +OAuthError: + $ref: './OAuthError.yaml' + +NotFound: + $ref: './NotFound.yaml' + +SwissUnauthorisedEdit: + $ref: './SwissUnauthorisedEdit.yaml' + +GameStream: + $ref: './GameStream.yaml' + +MoveStream: + $ref: './MoveStream.yaml' + +ExternalEngineRegistration: + $ref: './ExternalEngineRegistration.yaml' + +ExternalEngine: + $ref: './ExternalEngine.yaml' + +ExternalEngineWork: + $ref: './ExternalEngineWork.yaml' + +Timeline: + $ref: './Timeline.yaml' diff --git a/doc/specs/tags/account/api-account-email.yaml b/doc/specs/tags/account/api-account-email.yaml new file mode 100644 index 0000000..91de510 --- /dev/null +++ b/doc/specs/tags/account/api-account-email.yaml @@ -0,0 +1,25 @@ +get: + operationId: accountEmail + summary: Get my email address + description: | + Read the email address of the logged in user. + 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 diff --git a/doc/specs/tags/account/api-account-kid.yaml b/doc/specs/tags/account/api-account-kid.yaml new file mode 100644 index 0000000..ca828f6 --- /dev/null +++ b/doc/specs/tags/account/api-account-kid.yaml @@ -0,0 +1,56 @@ +get: + operationId: accountKid + summary: Get my kid mode status + description: | + Read the kid mode status of the logged in user. + - + 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. + - + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/account/api-account-preferences.yaml b/doc/specs/tags/account/api-account-preferences.yaml new file mode 100644 index 0000000..83e1e26 --- /dev/null +++ b/doc/specs/tags/account/api-account-preferences.yaml @@ -0,0 +1,28 @@ +get: + operationId: account + summary: Get my preferences + description: | + Read the preferences of the logged in user. + - + - + 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: '../../schemas/UserPreferences.yaml' + language: + type: string + example: en-GB diff --git a/doc/specs/tags/account/api-account.yaml b/doc/specs/tags/account/api-account.yaml new file mode 100644 index 0000000..ee20007 --- /dev/null +++ b/doc/specs/tags/account/api-account.yaml @@ -0,0 +1,21 @@ +get: + operationId: accountMe + summary: Get my profile + description: | + Public information about the logged in user. + 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: '../../schemas/UserExtended.yaml' diff --git a/doc/specs/tags/account/api-timeline.yaml b/doc/specs/tags/account/api-timeline.yaml new file mode 100644 index 0000000..38e06b7 --- /dev/null +++ b/doc/specs/tags/account/api-timeline.yaml @@ -0,0 +1,36 @@ +get: + operationId: timeline + summary: Get my timeline + description: | + Get the timeline events of the logged in user. + 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: '../../schemas/Timeline.yaml' diff --git a/doc/specs/tags/analysis/api-cloud-eval.yaml b/doc/specs/tags/analysis/api-cloud-eval.yaml new file mode 100644 index 0000000..8bb2d27 --- /dev/null +++ b/doc/specs/tags/analysis/api-cloud-eval.yaml @@ -0,0 +1,51 @@ +get: + operationId: apiCloudEval + summary: Get cloud evaluation of a position. + description: | + Get the cached evaluation of a position, if available. + Opening positions have more chances of being available. There are about 15 million positions in the database. + Up to 5 variations may be available. Variants are supported. + Use this endpoint to fetch a few positions here and there. + If you want to download a lot of positions, [get the full list](https://database.lichess.org/#evals) from our exported database. + 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: '../../schemas/VariantKey.yaml' + 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} + ] + } diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-games.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-games.yaml new file mode 100644 index 0000000..01d95cd --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-games.yaml @@ -0,0 +1,98 @@ +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. + Games are sorted by reverse chronological order (most recent first). + The game stream is throttled, depending on who is making the request: + - Anonymous request: 20 games per second + - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: false + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: false + 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: '../../schemas/GamePgn.yaml' + application/x-ndjson: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-join.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-join.yaml new file mode 100644 index 0000000..001e1eb --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-join.yaml @@ -0,0 +1,61 @@ +post: + operationId: apiTournamentJoin + summary: Join an Arena tournament + description: | + Join an Arena tournament, possibly with a password and/or a team. + Also unpauses if you had previously [paused](#operation/apiTournamentWithdraw) the tournament. + 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. + Can also be a [user-specific entry code](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code) + generated and shared by the organizer. + 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, + even if they are not connected to the tournament page. + This expires after one minute, to avoid pairing a user who is long gone. + You may call "join" again to extend the waiting. + responses: + "200": + description: The tournament was successfully joined. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/Ok.yaml' + "400": + description: Joining the tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-results.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-results.yaml new file mode 100644 index 0000000..5888dac --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-results.yaml @@ -0,0 +1,53 @@ +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). + **Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON)**, i.e. one JSON object per line. + If called on an ongoing tournament, results can be inconsistent + due to ranking changes while the players are being streamed. + Use on finished tournaments for guaranteed consistency. + 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. + It's an expensive server computation that slows down the stream. + 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" + } diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-teams.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-teams.yaml new file mode 100644 index 0000000..f0fac7b --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-teams.yaml @@ -0,0 +1,40 @@ +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). + 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" } } + ] + } + ] + } diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-terminate.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-terminate.yaml new file mode 100644 index 0000000..ceb771e --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-terminate.yaml @@ -0,0 +1,35 @@ +post: + operationId: apiTournamentTerminate + summary: Terminate an Arena tournament + description: | + Terminate an Arena tournament + 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: '../../schemas/Ok.yaml' + "400": + description: Terminating the tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament-id-withdraw.yaml b/doc/specs/tags/arenatournaments/api-tournament-id-withdraw.yaml new file mode 100644 index 0000000..56004c6 --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id-withdraw.yaml @@ -0,0 +1,36 @@ +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. + It's possible to join again later. Points and streaks are preserved. + 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: '../../schemas/Ok.yaml' + "400": + description: Pausing/leaving the tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament-id.yaml b/doc/specs/tags/arenatournaments/api-tournament-id.yaml new file mode 100644 index 0000000..cbddac0 --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-id.yaml @@ -0,0 +1,176 @@ +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. + 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: '../../schemas/ArenaTournamentVariantIsKey.yaml' +post: + operationId: apiTournamentUpdate + summary: Update an Arena tournament + description: | + Update an Arena tournament. + Be mindful not to make important changes to ongoing tournaments. + Can be used to update a team battle. + Additional restrictions: + - clockTime + clockIncrement > 0 + - 15s and 0+1 variant tournaments cannot be rated + - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150 + 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: '../../schemas/VariantKey.yaml' + rated: + type: boolean + description: Games are rated and impact players ratings + default: true + position: + $ref: '../../schemas/FromPositionFEN.yaml' + 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. + If this list is non-empty, then usernames absent from this list will be forbidden to join. + Adding `%titled` to the list additionally allows any titled player to join. + Example: `thibault,german11,%titled` + 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: '../../schemas/ArenaTournamentVariantIsKey.yaml' + "400": + description: The update of the Arena tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament-team-battle-id.yaml b/doc/specs/tags/arenatournaments/api-tournament-team-battle-id.yaml new file mode 100644 index 0000000..84951d1 --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament-team-battle-id.yaml @@ -0,0 +1,55 @@ +post: + operationId: apiTournamentTeamBattlePost + summary: Update a team battle + description: | + Set the teams and number of leaders of a team battle. + To update the other attributes of a team battle, use the [tournament update endpoint](#operation/apiTournamentUpdate). + 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. + Make sure to always send the full list. + Teams that are not in the list will be removed from the team battle. + Example: `coders,zhigalko_sergei-fan-club,hhSwTKZv` + nbLeaders: + 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: '../../schemas/ArenaTournamentVariantIsKey.yaml' + "400": + description: The update of the team battle tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-tournament.yaml b/doc/specs/tags/arenatournaments/api-tournament.yaml new file mode 100644 index 0000000..14f26b3 --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-tournament.yaml @@ -0,0 +1,180 @@ +get: + operationId: apiTournament + summary: Get current tournaments + description: | + Get recently finished, ongoing, and upcoming tournaments. + This API is used to display the [Lichess tournament schedule](https://lichess.org/tournament). + 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: '../../schemas/ArenaTournaments.yaml' +post: + operationId: apiTournamentPost + summary: Create a new Arena tournament + description: | + Create a public or private Arena tournament. + This endpoint mirrors the form on . + You can create up to 12 public tournaments per day, or 24 private tournaments. + A team battle can be created by specifying the `teamBattleByTeam` argument. + Additional restrictions: + - clockTime + clockIncrement > 0 + - 15s and 0+1 variant tournaments cannot be rated + - Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150 + 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: '../../schemas/VariantKey.yaml' + rated: + type: boolean + description: Games are rated and impact players ratings + default: true + position: + $ref: '../../schemas/FromPositionFEN.yaml' + 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 + # "conditions.titled": + # type: boolean + # description: Whether to require a title to enter the tournament + # default: false + 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. + You can also [generate user-specific entry codes](https://github.com/lichess-org/api/tree/master/example/tournament-entry-code) + based on this password. + teamBattleByTeam: + type: string + description: | + Set the ID of a team you lead to create a team battle. + The other teams can be added using the [team battle edit endpoint](#operation/apiTournamentTeamBattlePost). + conditions.teamMember.teamId: + type: string + description: | + Restrict entry to members of a team. + The teamId is the last part of a team URL, e.g. `https://lichess.org/team/coders` has teamId = `coders`. + Leave empty to let everyone join the tournament. + Do not use this to create team battles, use `teamBattleByTeam` instead. + conditions.minRating.rating: + 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. + If this list is non-empty, then usernames absent from this list will be forbidden to join. + Adding `%titled` to the list additionally allows any titled player to join. + Example: `thibault,german11,%titled` + 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: '../../schemas/ArenaTournamentVariantIsKey.yaml' + "400": + description: The creation of the Arena tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/arenatournaments/api-user-username-tournament-created.yaml b/doc/specs/tags/arenatournaments/api-user-username-tournament-created.yaml new file mode 100644 index 0000000..f2ffb48 --- /dev/null +++ b/doc/specs/tags/arenatournaments/api-user-username-tournament-created.yaml @@ -0,0 +1,39 @@ +get: + operationId: apiUserNameTournamentCreated + summary: Get tournaments created by a user + description: | + Get all tournaments created by a given user. + Tournaments are sorted by reverse chronological order of start date (last starting first). + Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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) + You can add this parameter more than once to include tournaments in different statuses. + Example: `?status=10&status=20` + 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: '../../schemas/ArenaTournament.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-abort.yaml b/doc/specs/tags/board/api-board-game-gameId-abort.yaml new file mode 100644 index 0000000..9a3dd1d --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-abort.yaml @@ -0,0 +1,34 @@ +post: + operationId: boardGameAbort + summary: Abort a game + description: | + Abort a game being played with the Board API. + 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: '../../schemas/Ok.yaml' + "400": + description: The abortion of the game failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-berserk.yaml b/doc/specs/tags/board/api-board-game-gameId-berserk.yaml new file mode 100644 index 0000000..a9f8940 --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-berserk.yaml @@ -0,0 +1,35 @@ +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. + Only available in arena tournaments that allow berserk, and before each player has made a move. + 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: '../../schemas/Ok.yaml' + "400": + description: The berserk has failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-chat.yaml b/doc/specs/tags/board/api-board-game-gameId-chat.yaml new file mode 100644 index 0000000..d2bc8dc --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-chat.yaml @@ -0,0 +1,73 @@ +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. + 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: '../../schemas/Ok.yaml' + "400": + description: The posting of the message in the chat failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' +get: + operationId: boardGameChatGet + summary: Fetch the game chat + description: | + Get the messages posted in the game chat + 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: '../../schemas/GameChat.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-claim-victory.yaml b/doc/specs/tags/board/api-board-game-gameId-claim-victory.yaml new file mode 100644 index 0000000..f99f9d0 --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-claim-victory.yaml @@ -0,0 +1,34 @@ +post: + operationId: boardGameClaimVictory + summary: Claim victory of a game + description: | + Claim victory when the opponent has left the game for a while. + 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: '../../schemas/Ok.yaml' + "400": + description: The victory claim has failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-draw-accept.yaml b/doc/specs/tags/board/api-board-game-gameId-draw-accept.yaml new file mode 100644 index 0000000..fa8ec12 --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-draw-accept.yaml @@ -0,0 +1,45 @@ +post: + operationId: boardGameDraw + summary: Handle draw offers + description: | + Create/accept/decline draw offers. + - `yes`: Offer a draw, or accept the opponent's draw offer. + - `no`: Decline a draw offer from the opponent. + 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: '../../schemas/Ok.yaml' + "400": + description: The draw offering failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-move-move.yaml b/doc/specs/tags/board/api-board-game-gameId-move-move.yaml new file mode 100644 index 0000000..73873a3 --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-move-move.yaml @@ -0,0 +1,47 @@ +post: + operationId: boardGameMove + summary: Make a Board move + description: | + Make a move in a game being played with the Board API. + The move can also contain a draw offer/agreement. + 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: '../../schemas/Ok.yaml' + "400": + description: The move failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-resign.yaml b/doc/specs/tags/board/api-board-game-gameId-resign.yaml new file mode 100644 index 0000000..263fc3b --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-resign.yaml @@ -0,0 +1,34 @@ +post: + operationId: boardGameResign + summary: Resign a game + description: | + Resign a game being played with the Board API. + 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: '../../schemas/Ok.yaml' + "400": + description: The resigning from the game failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-gameId-takeback-accept.yaml b/doc/specs/tags/board/api-board-game-gameId-takeback-accept.yaml new file mode 100644 index 0000000..2e12e55 --- /dev/null +++ b/doc/specs/tags/board/api-board-game-gameId-takeback-accept.yaml @@ -0,0 +1,45 @@ +post: + operationId: boardGameTakeback + summary: Handle takeback offers + description: | + Create/accept/decline takebacks. + - `yes`: Propose a takeback, or accept the opponent's takeback offer. + - `no`: Decline a takeback offer from the opponent. + 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: '../../schemas/Ok.yaml' + "400": + description: The takeback offering failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-board-game-stream-gameId.yaml b/doc/specs/tags/board/api-board-game-stream-gameId.yaml new file mode 100644 index 0000000..f286e9d --- /dev/null +++ b/doc/specs/tags/board/api-board-game-stream-gameId.yaml @@ -0,0 +1,61 @@ +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: '../../schemas/GameFullEvent.yaml' + - $ref: '../../schemas/GameStateEvent.yaml' + - $ref: '../../schemas/ChatLineEvent.yaml' + - $ref: '../../schemas/OpponentGone.yaml' + examples: + gameFull: + $ref: '../../examples/gameFull.yaml' + gameState: + $ref: '../../examples/gameState.yaml' + chatLine: + $ref: '../../examples/chatLine.yaml' + chatLineSpectator: + $ref: '../../examples/chatLineSpectator.yaml' + opponentGoneTrue: + $ref: '../../examples/opponentGoneTrue.yaml' + opponentGoneFalse: + $ref: '../../examples/opponentGoneFalse.yaml' + gameStateResign: + $ref: '../../examples/gameStateResign.yaml' + "404": + description: The game was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/board/api-board-seek.yaml b/doc/specs/tags/board/api-board-seek.yaml new file mode 100644 index 0000000..6af2096 --- /dev/null +++ b/doc/specs/tags/board/api-board-seek.yaml @@ -0,0 +1,89 @@ +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: '../../schemas/VariantKey.yaml' + 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. + Example: 1500-1800 + 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: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/board/api-stream-event.yaml b/doc/specs/tags/board/api-stream-event.yaml new file mode 100644 index 0000000..74ee602 --- /dev/null +++ b/doc/specs/tags/board/api-stream-event.yaml @@ -0,0 +1,47 @@ +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: '../../schemas/GameStartEvent.yaml' + - $ref: '../../schemas/GameFinishEvent.yaml' + - $ref: '../../schemas/ChallengeEvent.yaml' + - $ref: '../../schemas/ChallengeCanceledEvent.yaml' + - $ref: '../../schemas/ChallengeDeclinedEvent.yaml' + examples: + challenge: + $ref: '../../examples/challenge.yaml' + challengeCanceled: + $ref: '../../examples/challengeCanceled.yaml' + challengeDeclined: + $ref: '../../examples/challengeDeclined.yaml' + gameStart: + $ref: '../../examples/gameStart.yaml' + gameFinish: + $ref: '../../examples/gameFinish.yaml' diff --git a/doc/specs/tags/bot/api-bot-account-upgrade.yaml b/doc/specs/tags/bot/api-bot-account-upgrade.yaml new file mode 100644 index 0000000..904a486 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-account-upgrade.yaml @@ -0,0 +1,33 @@ +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. + The account **cannot have played any game** before becoming a Bot account. The upgrade is **irreversible**. The account will only be able to play as a Bot. + To upgrade an account to Bot, use the [official lichess-bot client](https://github.com/lichess-bot-devs/lichess-bot), or follow these steps: + - Create an [API access token](https://lichess.org/account/oauth/token/create?scopes[]=bot:play) with "Play bot moves" permission. + - `curl -d '' https://lichess.org/api/bot/account/upgrade -H "Authorization: Bearer "` + To know if an account has already been upgraded, use the [Get my profile API](#operation/accountMe): + the `title` field should be set to `BOT`. + 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: '../../schemas/Ok.yaml' + "400": + description: The upgrade of the bot account failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-gameId-abort.yaml b/doc/specs/tags/bot/api-bot-game-gameId-abort.yaml new file mode 100644 index 0000000..6c0e553 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-gameId-abort.yaml @@ -0,0 +1,34 @@ +post: + operationId: botGameAbort + summary: Abort a game + description: | + Abort a game being played with the Bot API. + 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: '../../schemas/Ok.yaml' + "400": + description: The abortion of the game failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-gameId-chat.yaml b/doc/specs/tags/bot/api-bot-game-gameId-chat.yaml new file mode 100644 index 0000000..86400aa --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-gameId-chat.yaml @@ -0,0 +1,80 @@ +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. + 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: '../../schemas/Ok.yaml' + "400": + description: The posting of the message in chat failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' +get: + operationId: botGameChatGet + summary: Fetch the game chat + description: | + Get the messages posted in the game chat + 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: '../../schemas/GameChat.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-gameId-draw-accept.yaml b/doc/specs/tags/bot/api-bot-game-gameId-draw-accept.yaml new file mode 100644 index 0000000..fb80779 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-gameId-draw-accept.yaml @@ -0,0 +1,45 @@ +post: + operationId: botGameDraw + summary: Handle draw offers in bot games + description: | + Create/accept/decline draw offers in bot games + - `yes`: Offer a draw, or accept the opponent's draw offer. + - `no`: Decline a draw offer from the opponent. + 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: '../../schemas/Ok.yaml' + "400": + description: The draw offering failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-gameId-move-move.yaml b/doc/specs/tags/bot/api-bot-game-gameId-move-move.yaml new file mode 100644 index 0000000..eeba949 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-gameId-move-move.yaml @@ -0,0 +1,47 @@ +post: + operationId: botGameMove + summary: Make a Bot move + description: | + Make a move in a game being played with the Bot API. + The move can also contain a draw offer/agreement. + 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: '../../schemas/Ok.yaml' + "400": + description: The bot move failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-gameId-resign.yaml b/doc/specs/tags/bot/api-bot-game-gameId-resign.yaml new file mode 100644 index 0000000..9d6bf8a --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-gameId-resign.yaml @@ -0,0 +1,34 @@ +post: + operationId: botGameResign + summary: Resign a game + description: | + Resign a game being played with the Bot API. + 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: '../../schemas/Ok.yaml' + "400": + description: Resigning the game failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/bot/api-bot-game-stream-gameId.yaml b/doc/specs/tags/bot/api-bot-game-stream-gameId.yaml new file mode 100644 index 0000000..f1adcc0 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-game-stream-gameId.yaml @@ -0,0 +1,60 @@ +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: '../../schemas/GameFullEvent.yaml' + - $ref: '../../schemas/GameStateEvent.yaml' + - $ref: '../../schemas/ChatLineEvent.yaml' + - $ref: '../../schemas/OpponentGone.yaml' + examples: + gameFull: + $ref: '../../examples/gameFull.yaml' + gameState: + $ref: '../../examples/gameState.yaml' + chatLine: + $ref: '../../examples/chatLine.yaml' + chatLineSpectator: + $ref: '../../examples/chatLineSpectator.yaml' + opponentGoneTrue: + $ref: '../../examples/opponentGoneTrue.yaml' + opponentGoneFalse: + $ref: '../../examples/opponentGoneFalse.yaml' + gameStateResign: + $ref: '../../examples/gameStateResign.yaml' + "404": + description: The bot game was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/bot/api-bot-online.yaml b/doc/specs/tags/bot/api-bot-online.yaml new file mode 100644 index 0000000..70b1fa6 --- /dev/null +++ b/doc/specs/tags/bot/api-bot-online.yaml @@ -0,0 +1,27 @@ +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: '../../schemas/User.yaml' diff --git a/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentId.pgn.yaml b/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentId.pgn.yaml new file mode 100644 index 0000000..8994b14 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentId.pgn.yaml @@ -0,0 +1,31 @@ +get: + operationId: broadcastAllRoundsPgn + summary: Export all rounds as PGN + description: | + Download all games of all rounds of a broadcast in PGN format. + If a `study:read` [OAuth token](#tag/OAuth) is provided, + the private rounds where the user is a contributor will be available. + You may want to [download only the games of a single round](#operation/broadcastRoundPgn) instead. + 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: '../../schemas/StudyPgn.yaml' diff --git a/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentSlug-broadcastRoundSlug-broadcastRoundId.yaml b/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentSlug-broadcastRoundSlug-broadcastRoundId.yaml new file mode 100644 index 0000000..bd50aca --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcast-broadcastTournamentSlug-broadcastRoundSlug-broadcastRoundId.yaml @@ -0,0 +1,33 @@ +get: + operationId: broadcastRoundGet + summary: Get a broadcast round + description: | + Get information about a broadcast round. + tags: + - Broadcasts + 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: '../../schemas/BroadcastRound.yaml' diff --git a/doc/specs/tags/broadcasts/api-broadcast-my-rounds.yaml b/doc/specs/tags/broadcasts/api-broadcast-my-rounds.yaml new file mode 100644 index 0000000..b87da59 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcast-my-rounds.yaml @@ -0,0 +1,27 @@ +get: + operationId: broadcastMyRoundsGet + summary: Get your broadcast rounds + description: | + Stream all broadcast rounds you are a member of. + Also includes broadcasts rounds you did not create, but were invited to. + Also includes broadcasts rounds where you're a non-writing member. See the `writeable` flag in the response. + Rounds are ordered by rank, which is roughly chronological, most recent first, slightly pondered with popularity. + 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: '../../schemas/BroadcastMyRound.yaml' diff --git a/doc/specs/tags/broadcasts/api-broadcast-round-broadcastRoundId.pgn.yaml b/doc/specs/tags/broadcasts/api-broadcast-round-broadcastRoundId.pgn.yaml new file mode 100644 index 0000000..aa60937 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcast-round-broadcastRoundId.pgn.yaml @@ -0,0 +1,31 @@ +get: + operationId: broadcastRoundPgn + summary: Export one round as PGN + description: | + Download all games of a single round of a broadcast tournament in PGN format. + You *could* poll this endpoint to get updates about a tournament, but it would be slow, + and very inneficient. + Instead, consider [streaming the tournament](#operation/broadcastStreamRoundPgn) to get + a new PGN every time a game is updated, in real-time. + 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: '../../schemas/StudyPgn.yaml' diff --git a/doc/specs/tags/broadcasts/api-broadcast.yaml b/doc/specs/tags/broadcasts/api-broadcast.yaml new file mode 100644 index 0000000..3d209d9 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcast.yaml @@ -0,0 +1,32 @@ +get: + operationId: broadcastIndex + summary: Get official broadcasts + description: | + Get all incoming, ongoing, and finished official broadcasts. + The broadcasts are sorted by start date, most recent first. + Broadcasts are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/BroadcastTour.yaml' diff --git a/doc/specs/tags/broadcasts/api-stream-broadcast-round-broadcastRoundId.pgn.yaml b/doc/specs/tags/broadcasts/api-stream-broadcast-round-broadcastRoundId.pgn.yaml new file mode 100644 index 0000000..39fba19 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-stream-broadcast-round-broadcastRoundId.pgn.yaml @@ -0,0 +1,31 @@ +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. + Then, it waits for new moves to be played. As soon as it happens, the entire PGN of the game is sent to the stream. + The stream will also send PGNs when games are added to the tournament. + This is the best way to get updates about an ongoing tournament. Streaming means no polling, + and no pollings means no latency, and minimum impact on the server. + 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: '../../schemas/StudyPgn.yaml' diff --git a/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-edit.yaml b/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-edit.yaml new file mode 100644 index 0000000..f1fb044 --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-edit.yaml @@ -0,0 +1,42 @@ +post: + operationId: broadcastTourUpdate + summary: Update your broadcast tournament + description: | + Update information about a broadcast tournament that you created. + This endpoint accepts the same form data as the web form. + All fields must be populated with data. Missing fields will override the broadcast with empty data. + 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: '../../schemas/BroadcastForm.yaml' + responses: + "200": + description: The broadcast tournament was successfully edited. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/Ok.yaml' + "400": + description: The edition of the broadcast tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-new.yaml b/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-new.yaml new file mode 100644 index 0000000..070f2a9 --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-broadcastTournamentId-new.yaml @@ -0,0 +1,83 @@ +post: + operationId: broadcastRoundCreate + summary: Create a broadcast round + description: | + Create a new broadcast round to relay external games. + This endpoint accepts the same form data as the web form. + 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. + Example: `Round 1` + syncUrl: + type: string + description: | + URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet. + Example: `https://myserver.org/myevent/round-10/games.pgn` + If the syncUrl is missing, then the broadcast needs to be fed by [pushing PGN to it](#operation/broadcastPush). + syncUrlRound: + type: string + description: | + Required if `syncUrl` contains a livechesscloud link. + startsAt: + type: integer + description: | + Timestamp in milliseconds of broadcast round start. Leave empty to manually start the broadcast round. + Example: `1356998400070` + 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. + Example: `900` (15 min) + minimum: 0 + maximum: 1800 + period: + type: integer + description: | + (Only for Admins) Waiting time for each poll. + minimum: 2 + maximum: 60 + finished: + type: boolean + description: | + Mark whether the round has been completed. + 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: '../../schemas/BroadcastRound.yaml' + "400": + description: The creation of the broadcast failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/broadcasts/broadcast-new.yaml b/doc/specs/tags/broadcasts/broadcast-new.yaml new file mode 100644 index 0000000..2abc36a --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-new.yaml @@ -0,0 +1,34 @@ +post: + operationId: broadcastTourCreate + summary: Create a broadcast tournament + description: | + Create a new broadcast tournament to relay external games. + This endpoint accepts the same form data as the [web form](https://lichess.org/broadcast/new). + tags: + - Broadcasts + security: + - OAuth2: ["study:write"] + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + $ref: '../../schemas/BroadcastForm.yaml' + responses: + "200": + description: The broadcast tournament was successfully created. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/BroadcastTour.yaml' + "400": + description: The creation of the broadcast tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-edit.yaml b/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-edit.yaml new file mode 100644 index 0000000..c293bba --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-edit.yaml @@ -0,0 +1,84 @@ +post: + operationId: broadcastRoundUpdate + summary: Update your broadcast round + description: | + Update information about a broadcast round that you created. + This endpoint accepts the same form data as the web form. + All fields must be populated with data. Missing fields will override the broadcast with empty data. + For instance, if you omit `startDate`, then any pre-existing start date will be removed. + 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. + Example: `Round 10` + syncUrl: + type: string + description: | + URL that Lichess will poll to get updates about the games. It must be publicly accessible from the Internet. + Example: `https://myserver.org/myevent/round-10/games.pgn` + syncUrlRound: + type: string + description: | + Required if `syncUrl` contains a livechesscloud link. + startsAt: + type: integer + description: | + Timestamp in milliseconds of broadcast start. Leave empty to manually start the broadcast. + Example: `1356998400070` + 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. + Example: `900` (15 min) + minimum: 0 + maximum: 1800 + period: + type: integer + description: | + (Only for Admins) Waiting time for each poll. + minimum: 2 + maximum: 60 + finished: + type: boolean + description: | + Mark whether the round has been completed. + 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: '../../schemas/Ok.yaml' + "400": + description: The edition of the broadcast tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-push.yaml b/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-push.yaml new file mode 100644 index 0000000..d4983e4 --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-round-broadcastRoundId-push.yaml @@ -0,0 +1,55 @@ +post: + operationId: broadcastPush + summary: Push PGN to your broadcast round + description: | + Update your broadcast with new PGN. + Only for broadcast without a source URL. + 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 + responses: + "200": + description: The broadcast was successfully updated. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + properties: + moves: + type: integer + example: + moves: 12 + "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" diff --git a/doc/specs/tags/broadcasts/broadcast-slug-broadcastTournamentId.yaml b/doc/specs/tags/broadcasts/broadcast-slug-broadcastTournamentId.yaml new file mode 100644 index 0000000..5f712a8 --- /dev/null +++ b/doc/specs/tags/broadcasts/broadcast-slug-broadcastTournamentId.yaml @@ -0,0 +1,29 @@ +get: + operationId: broadcastTourGet + summary: Get your broadcast tournament + description: | + Get information about a broadcast tournament. + tags: + - Broadcasts + security: + - OAuth2: ["study:read"] + parameters: + - in: path + name: slug + description: The broadcast tournament slug. Only used for SEO, the slug can be safely replaced by `-`. Only the `broadcastTournamentId` is actually used. + required: true + schema: + type: string + - 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: '../../schemas/BroadcastTour.yaml' diff --git a/doc/specs/tags/bulkpairings/api-bulk-pairing-id-start-clocks.yaml b/doc/specs/tags/bulkpairings/api-bulk-pairing-id-start-clocks.yaml new file mode 100644 index 0000000..1be32f2 --- /dev/null +++ b/doc/specs/tags/bulkpairings/api-bulk-pairing-id-start-clocks.yaml @@ -0,0 +1,38 @@ +post: + operationId: bulkPairingStartClocks + summary: Manually start clocks + description: | + Immediately start all clocks of the games of a bulk pairing. + This overrides the `startClocksAt` value of an existing bulk pairing. + If the games have not yet been created (`bulk.pairAt` is in the future), then this does nothing. + If the clocks have already started (`bulk.startClocksAt` is in the past), then this does nothing. + 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: '../../schemas/Ok.yaml' + "404": + description: The bulk pairing was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/bulkpairings/api-bulk-pairing-id.yaml b/doc/specs/tags/bulkpairings/api-bulk-pairing-id.yaml new file mode 100644 index 0000000..51c1391 --- /dev/null +++ b/doc/specs/tags/bulkpairings/api-bulk-pairing-id.yaml @@ -0,0 +1,72 @@ +get: + operationId: bulkPairingGet + summary: Show a bulk pairing + description: | + Get a single bulk pairing by its ID. + 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: '../../schemas/BulkPairing.yaml' + "404": + description: The bulk pairing was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' +delete: + operationId: bulkPairingDelete + summary: Cancel a bulk pairing + description: | + Cancel and delete a bulk pairing that is scheduled in the future. + If the games have already been created, then this does nothing. + Canceling a bulk pairing does not refund the rate limit cost of that bulk pairing. + 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: '../../schemas/Ok.yaml' + "404": + description: The bulk pairing to delete was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/bulkpairings/api-bulk-pairing.yaml b/doc/specs/tags/bulkpairings/api-bulk-pairing.yaml new file mode 100644 index 0000000..4accc56 --- /dev/null +++ b/doc/specs/tags/bulkpairings/api-bulk-pairing.yaml @@ -0,0 +1,149 @@ +get: + operationId: bulkPairingList + summary: View your bulk pairings + description: | + Get a list of bulk pairings you created. + 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: '../../schemas/BulkPairing.yaml' +post: + operationId: bulkPairingCreate + summary: Create a bulk pairing + description: | + Schedule many games at once, up to 24h in advance. + OAuth tokens are required for all paired players, with the `challenge:write` scope. + You can schedule up to 500 games every 10 minutes. [Contact us](mailto:contact@lichess.org) if you need higher limits. + If games have a real-time clock, each player must have only one pairing. + For correspondence games, players can have multiple pairings within the same bulk. + The entire bulk is rejected if: + - a token is missing + - a token is present more than once (except in correspondence) + - a token lacks the `challenge:write` scope + - a player account is closed + - a player is paired more than once (except in correspondence) + - a bulk is already scheduled to start at the same time with the same player + - you have 20 scheduled bulks + - you have 1000 scheduled games + Partial bulks are never created. Either it all fails, or it all succeeds. + When it fails, it does so with an error message explaining the issue. + Failed bulks are not counted in the rate limiting, they are free. + Fix the issues, manually or programmatically, then retry to schedule the bulk. + A successful bulk creation returns a JSON bulk document. Its ID can be used for further operations. + 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,...`. + The 2 tokens of the players of a game are separated with `:`. The first token gets the white pieces. Games are separated with `,`. + Up to 1000 tokens can be sent, for a max of 500 games. + Each token must be included at most once. + Example: `token1:token2,token3:token4,token5:token6` + 'clock.limit': + type: number + description: | + Clock initial time in seconds. Example: `600` + minimum: 0 + maximum: 10800 + 'clock.increment': + type: integer + description: | + Clock increment in seconds. Example: `2` + 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. + Up to 7 days in the future. + Omit, or set to current date and time, to start the games immediately. + Example: `1612289869919` + type: integer + startClocksAt: + description: | + Date at which the clocks will be automatically started as a Unix timestamp in milliseconds. + Up to 7 days in the future. + Note that the clocks can start earlier than specified, if players start making moves in the game. + If omitted, the clocks will not start automatically. + Example: `1612289869919` + type: integer + rated: + type: boolean + description: Game is rated and impacts players ratings + default: false + variant: + $ref: '../../schemas/VariantKey.yaml' + fen: + $ref: '../../schemas/FromPositionFEN.yaml' + message: + type: string + description: | + Message that will be sent to each player, when the game is created. It is sent from your user account. + `{opponent}` and `{game}` are placeholders that will be replaced with the opponent and the game URLs. + You can omit this field to send the default message, + but if you set your own message, it must at least contain the `{game}` placeholder. + default: "Your game with {opponent} is ready: {game}." + rules: + type: string + enum: + - noAbort + - noRematch + - noGiveTime + - noClaimWin + - noEarlyDraw + description: | + Extra game rules separated by commas. + Example: `noAbort,noRematch` + responses: + "200": + description: The bulk pairing has been successfully created. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/BulkPairing.yaml' + "400": + description: The creation of the bulk pairings failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-ai.yaml b/doc/specs/tags/challenges/api-challenge-ai.yaml new file mode 100644 index 0000000..14b1775 --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-ai.yaml @@ -0,0 +1,76 @@ +post: + operationId: challengeAi + summary: Challenge the AI + description: | + Start a game with Lichess AI. + You will be notified on the [event stream](#operation/apiStreamEvent) that a new game has started. + 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: '../../schemas/VariantKey.yaml' + fen: + $ref: '../../schemas/FromPositionFEN.yaml' + 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: '../../schemas/GameJson.yaml' + "400": + description: The creation of a game with Lichess AI failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-accept.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-accept.yaml new file mode 100644 index 0000000..36fb9da --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-challengeId-accept.yaml @@ -0,0 +1,35 @@ +post: + operationId: challengeAccept + summary: Accept a challenge + description: | + Accept an incoming challenge. + You should receive a `gameStart` event on the [incoming events stream](#operation/apiStreamEvent). + 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: '../../schemas/Ok.yaml' + "404": + description: The challenge to accept was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-cancel.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-cancel.yaml new file mode 100644 index 0000000..3b7116f --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-challengeId-cancel.yaml @@ -0,0 +1,41 @@ +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. + Note that the ID of a game is the same as the ID of the challenge that created it. + Works for user challenges and open challenges alike. + 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: '../../schemas/Ok.yaml' + "404": + description: The challenge to cancel was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-challengeId-decline.yaml b/doc/specs/tags/challenges/api-challenge-challengeId-decline.yaml new file mode 100644 index 0000000..fb5d2ab --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-challengeId-decline.yaml @@ -0,0 +1,57 @@ +post: + operationId: challengeDecline + summary: Decline a challenge + description: | + Decline an incoming challenge. + 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: '../../schemas/Ok.yaml' + "404": + description: The challenge to decline was not found. + content: + application/json: + schema: + $ref: '../../schemas/NotFound.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-gameId-start-clocks.yaml b/doc/specs/tags/challenges/api-challenge-gameId-start-clocks.yaml new file mode 100644 index 0000000..7a6de77 --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-gameId-start-clocks.yaml @@ -0,0 +1,40 @@ +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. + Requires the OAuth tokens of both players with `challenge:write` scope. + If the clocks have already started, the call will have no effect. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-open.yaml b/doc/specs/tags/challenges/api-challenge-open.yaml new file mode 100644 index 0000000..5337a10 --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-open.yaml @@ -0,0 +1,98 @@ +post: + operationId: challengeOpen + summary: Open-ended challenge + description: | + Create a challenge that any 2 players can join. + Share the URL of the challenge. the first 2 players to click it will be paired for a game. + The response body also contains `whiteUrl` and `blackUrl`. + You can control which color each player gets by giving them these URLs, + instead of the main challenge URL. + Open challenges expire after 24h. + If the challenge creation is [authenticated with OAuth2](#section/Introduction/Authentication), + then you can use the [challenge cancel endpoint](#operation/challengeCancel) to cancel it. + To directly pair 2 known players, use [this endpoint](#operation/bulkPairingList) instead. + 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: '../../schemas/VariantKey.yaml' + fen: + $ref: '../../schemas/FromPositionFEN.yaml' + 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. + Example: `noRematch,noGiveTime` + The `noAbort` rule is available for Lichess admins only + users: + type: string + description: | + Optional pair of usernames, separated by a comma. + If set, only these users will be allowed to join the game. + The first username gets the white pieces. + Example: `Username1,Username2` + 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: '../../schemas/ChallengeOpenJson.yaml' + "400": + description: The creation of the challenge failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/challenges/api-challenge-username.yaml b/doc/specs/tags/challenges/api-challenge-username.yaml new file mode 100644 index 0000000..c66619c --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge-username.yaml @@ -0,0 +1,107 @@ +post: + operationId: challengeCreate + summary: Create a challenge + description: | + Challenge someone to play. The targeted player can choose to accept or decline. + If the challenge is accepted, you will be notified on the [event stream](#operation/apiStreamEvent) + that a new game has started. The game ID will be the same as the challenge ID. + Challenges for realtime games (not correspondence) expire after 20s if not accepted. + To prevent that, use the `keepAliveStream` flag described below. + 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: '../../schemas/VariantKey.yaml' + fen: + $ref: '../../schemas/FromPositionFEN.yaml' + keepAliveStream: + type: boolean + description: | + If set, the response is streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + The challenge is kept alive until the connection is closed by the client. + When the challenge is accepted, declined or canceled, a message of the form `{"done":"accepted"}` is sent, + then the connection is closed by the server. + If not set, the response is not streamed, and the challenge expires after 20s if not accepted. + rules: + type: string + enum: + - noAbort + - noRematch + - noGiveTime + - noClaimWin + - noEarlyDraw + description: | + Extra game rules separated by commas. + Example: `noAbort,noRematch` + 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: '../../schemas/ChallengeJson.yaml' + "400": + description: The creation of the challenge failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/challenges/api-challenge.yaml b/doc/specs/tags/challenges/api-challenge.yaml new file mode 100644 index 0000000..fb94dc1 --- /dev/null +++ b/doc/specs/tags/challenges/api-challenge.yaml @@ -0,0 +1,32 @@ +get: + operationId: challengeList + summary: List your challenges + description: | + Get a list of challenges created by or targeted at you. + 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: '../../schemas/ChallengeJson.yaml' + out: + type: array + description: Outgoing challenges i.e. created by you + items: + $ref: '../../schemas/ChallengeJson.yaml' diff --git a/doc/specs/tags/challenges/api-round-gameId-add-time-seconds.yaml b/doc/specs/tags/challenges/api-round-gameId-add-time-seconds.yaml new file mode 100644 index 0000000..e6f7280 --- /dev/null +++ b/doc/specs/tags/challenges/api-round-gameId-add-time-seconds.yaml @@ -0,0 +1,36 @@ +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. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/challenges/api-token-admin-challenge.yaml b/doc/specs/tags/challenges/api-token-admin-challenge.yaml new file mode 100644 index 0000000..a7e4571 --- /dev/null +++ b/doc/specs/tags/challenges/api-token-admin-challenge.yaml @@ -0,0 +1,46 @@ +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.* + Create and obtain `challenge:write` tokens for multiple users. + If a similar token already exists for a user, it is reused. This endpoint is idempotent. + 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: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/externalengine/api-external-engine-id-analyse.yaml b/doc/specs/tags/externalengine/api-external-engine-id-analyse.yaml new file mode 100644 index 0000000..624fcc4 --- /dev/null +++ b/doc/specs/tags/externalengine/api-external-engine-id-analyse.yaml @@ -0,0 +1,99 @@ +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`** + Request analysis from an external engine. + Response content is streamed as [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). + The properties are based on the [UCI specification](https://backscattering.de/chess/uci/#engine). + Analysis stops when the client goes away, the requested limit + is reached, or the provider goes away. + requestBody: + description: Engine credentials and analysis request. + required: true + content: + application/json: + schema: + type: object + properties: + clientSecret: + type: string + example: ees_mdF2hK0hlKGSPeC6 + work: + $ref: '../../schemas/ExternalEngineWork.yaml' + 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 diff --git a/doc/specs/tags/externalengine/api-external-engine-id.yaml b/doc/specs/tags/externalengine/api-external-engine-id.yaml new file mode 100644 index 0000000..fa58648 --- /dev/null +++ b/doc/specs/tags/externalengine/api-external-engine-id.yaml @@ -0,0 +1,73 @@ +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. + responses: + "200": + description: A registered engine. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/ExternalEngine.yaml' +put: + operationId: apiExternalEnginePut + summary: Update external engine + tags: + - External engine + security: + - OAuth2: ["engine:write"] + description: | + Updates the properties of an external engine. + requestBody: + description: A modified engine registration. + required: true + content: + application/json: + schema: + $ref: '../../schemas/ExternalEngineRegistration.yaml' + responses: + "200": + description: A registered engine. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/ExternalEngine.yaml' +delete: + operationId: apiExternalEngineDelete + summary: Delete external engine + tags: + - External engine + security: + - OAuth2: ["engine:write"] + description: | + Unregisters an external engine. + responses: + "200": + description: Engine successfully deleted + content: + application/json: + schema: + $ref: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/externalengine/api-external-engine-work-id.yaml b/doc/specs/tags/externalengine/api-external-engine-work-id.yaml new file mode 100644 index 0000000..10660bd --- /dev/null +++ b/doc/specs/tags/externalengine/api-external-engine-work-id.yaml @@ -0,0 +1,45 @@ +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}`** + Submit a stream of analysis as [UCI output](https://backscattering.de/chess/uci/#engine-info). + * The engine should always be in `UCI_Chess960` mode. + * `UCI_AnalyseMode` enabled if available. + * It produces `info` with at least: + - `depth` + - `multipv` (between 1 and 5) + - `score` + - `nodes` + - `time` + - `pv` + The server may close the connection at any time, indicating that + the requester has gone away and analysis should be stopped. + 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: "'*'" diff --git a/doc/specs/tags/externalengine/api-external-engine-work.yaml b/doc/specs/tags/externalengine/api-external-engine-work.yaml new file mode 100644 index 0000000..286a22d --- /dev/null +++ b/doc/specs/tags/externalengine/api-external-engine-work.yaml @@ -0,0 +1,59 @@ +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`** + Wait for an analysis requests to any of the external engines that + have been registered with the given `secret`. + Uses long polling. + After acquiring a request, the provider should immediately + [start streaming the results](#tag/External-engine/operation/apiExternalEngineSubmit). + 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: '../../schemas/ExternalEngineWork.yaml' + engine: + $ref: '../../schemas/ExternalEngine.yaml' + required: + - id + - engine + - work + "204": + description: No pending analysis + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" diff --git a/doc/specs/tags/externalengine/api-external-engine.yaml b/doc/specs/tags/externalengine/api-external-engine.yaml new file mode 100644 index 0000000..83d4892 --- /dev/null +++ b/doc/specs/tags/externalengine/api-external-engine.yaml @@ -0,0 +1,54 @@ +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, + and the credentials required to use them. + 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: '../../schemas/ExternalEngine.yaml' +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 + and used on the analysis board. + After registering, the provider should start waiting for analyis requests. + requestBody: + description: A new external engine registration. + required: true + content: + application/json: + schema: + $ref: '../../schemas/ExternalEngineRegistration.yaml' + responses: + "200": + description: The registered engine. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/ExternalEngine.yaml' diff --git a/doc/specs/tags/games/api-account-playing.yaml b/doc/specs/tags/games/api-account-playing.yaml new file mode 100644 index 0000000..40b33cf --- /dev/null +++ b/doc/specs/tags/games/api-account-playing.yaml @@ -0,0 +1,51 @@ +get: + operationId: apiAccountPlaying + summary: Get my ongoing games + description: | + Get the ongoing games of the current user. + Real-time and correspondence games are included. + The most urgent games are listed first. + tags: + - Games + security: + - OAuth2: [] + parameters: + - in: query + name: nb + description: Max number of games to fetch + schema: + type: integer + default: 9 + minimum: 1 + maximum: 50 + responses: + "200": + description: The ongoing games of the logged in user. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + 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" } + } + ] + } diff --git a/doc/specs/tags/games/api-games-export-_ids.yaml b/doc/specs/tags/games/api-games-export-_ids.yaml new file mode 100644 index 0000000..0f92cfd --- /dev/null +++ b/doc/specs/tags/games/api-games-export-_ids.yaml @@ -0,0 +1,110 @@ +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. + Games are sorted by reverse chronological order (most recent first) + The method is `POST` so a longer list of IDs can be sent in the request body. + 300 IDs can be submitted. + Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: false + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: false + - in: query + name: literate + description: | + Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. + Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` + schema: + type: boolean + default: false + - in: query + name: players + description: | + URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. + Example: + 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: '../../schemas/GamePgn.yaml' + application/x-ndjson: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/games/api-games-export-imports.yaml b/doc/specs/tags/games/api-games-export-imports.yaml new file mode 100644 index 0000000..94f03a5 --- /dev/null +++ b/doc/specs/tags/games/api-games-export-imports.yaml @@ -0,0 +1,20 @@ +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: '../../schemas/GamePgn.yaml' diff --git a/doc/specs/tags/games/api-games-user-username.yaml b/doc/specs/tags/games/api-games-user-username.yaml new file mode 100644 index 0000000..f554ac7 --- /dev/null +++ b/doc/specs/tags/games/api-games-user-username.yaml @@ -0,0 +1,193 @@ +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. + Games are sorted by reverse chronological order (most recent first). + We recommend streaming the response, for it can be very long. + for instance has more than 500,000 games. + The game stream is throttled, depending on who is making the request: + - Anonymous request: 20 games per second + - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second + - Authenticated, downloading your own games: 60 games per second + 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: '../../schemas/PerfType.yaml' + - 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: false + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: false + - in: query + name: ongoing + description: Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. + schema: + type: boolean + default: false + - in: query + name: finished + description: Include finished games. Set to `false` to only get ongoing games. + schema: + type: boolean + default: true + - in: query + name: literate + description: | + Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. + Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` + schema: + type: boolean + default: false + - in: query + name: lastFen + description: | + Include the FEN notation of the last position of the game. + The response type must be set to `application/x-ndjson` by the request `Accept` header. + schema: + type: boolean + default: false + - in: query + name: players + description: | + URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. + Example: + 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: '../../schemas/GamePgn.yaml' + application/x-ndjson: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/games/api-import.yaml b/doc/specs/tags/games/api-import.yaml new file mode 100644 index 0000000..43da4b7 --- /dev/null +++ b/doc/specs/tags/games/api-import.yaml @@ -0,0 +1,37 @@ +post: + operationId: gameImport + summary: Import one game + description: | + Import a game from PGN. See . + Rate limiting: 200 games per hour for OAuth requests, 100 games per hour for anonymous requests. + To broadcast ongoing games, consider [pushing to a broadcast instead](#operation/broadcastPush). + To analyse a position or a line, just construct an analysis board URL: + [https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+](https://lichess.org/analysis/pgn/e4_e5_Nf3_Nc6_Bc4_Bc5_Bxf7+) + 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"} + diff --git a/doc/specs/tags/games/api-stream-game-id.yaml b/doc/specs/tags/games/api-stream-game-id.yaml new file mode 100644 index 0000000..b1752dc --- /dev/null +++ b/doc/specs/tags/games/api-stream-game-id.yaml @@ -0,0 +1,27 @@ +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). + A description of the game is sent as a first message. + Then a message is sent each time a move is played. + Finally a description of the game is sent when it finishes, and the stream is closed. + Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. + No more than 8 game streams can be opened at the same time from the same IP address. + 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: '../../schemas/MoveStream.yaml' diff --git a/doc/specs/tags/games/api-stream-games-by-users.yaml b/doc/specs/tags/games/api-stream-games-by-users.yaml new file mode 100644 index 0000000..4a3ca12 --- /dev/null +++ b/doc/specs/tags/games/api-stream-games-by-users.yaml @@ -0,0 +1,42 @@ +post: + operationId: gamesByUsers + summary: Stream games of users + description: | + Stream the games played between a list of users, in real time. + Only games where **both players** are part of the list are included. + The stream emits an event each time a game is started or finished. + To also get all current ongoing games at the beginning of the stream, use the `withCurrentGames` flag. + Games are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + Maximum number of users: 300. + The method is `POST` so a longer list of IDs can be sent in the request body. + tags: + - Games + security: [] + requestBody: + description: | + Up to 300 user IDs separated by commas. + Example: `aliquantus,chess-network,lovlas` + 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: '../../schemas/GameStream.yaml' diff --git a/doc/specs/tags/games/api-stream-games-streamId-add.yaml b/doc/specs/tags/games/api-stream-games-streamId-add.yaml new file mode 100644 index 0000000..1380a39 --- /dev/null +++ b/doc/specs/tags/games/api-stream-games-streamId-add.yaml @@ -0,0 +1,38 @@ +post: + operationId: gamesByIdsAdd + summary: Add game IDs to stream + description: | + Add new game IDs for [an existing stream](#operation/gamesByIds) to watch. + The stream will immediately outputs the games that already exists, then emit an event each time a game is started or finished. + tags: + - Games + security: [] + parameters: + - in: path + name: streamId + schema: + type: string + description: The stream ID you used to [create the stream](#operation/gamesByIds). + example: "myAppName-someRandomId" + required: true + requestBody: + description: | + Up to 500 or 1000 game IDs separated by commas. + Example: `gameId04,gameId05,gameId06` + required: true + content: + text/plain: + schema: + type: string + responses: + "200": + description: The game IDs have been added to the stream. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/games/api-stream-games-streamId.yaml b/doc/specs/tags/games/api-stream-games-streamId.yaml new file mode 100644 index 0000000..cb5a182 --- /dev/null +++ b/doc/specs/tags/games/api-stream-games-streamId.yaml @@ -0,0 +1,41 @@ +post: + operationId: gamesByIds + summary: Stream games by IDs + description: | + Creates a stream of games from an arbitrary streamId, and a list of game IDs. + The stream first outputs the games that already exists, then emits an event each time a game is started or finished. + Games are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + Maximum number of games: 500 for anonymous requests, or 1000 for [OAuth2 authenticated](#section/Introduction/Authentication) requests. + While the stream is open, it is possible to [add new game IDs to watch](#operation/gamesByIdsAdd). + tags: + - Games + security: [] + parameters: + - in: path + name: streamId + schema: + type: string + description: Arbitrary stream ID that you can later use to add game IDs to the stream. + example: "myAppName-someRandomId" + required: true + requestBody: + description: | + Up to 500 or 1000 game IDs separated by commas. + Example: `gameId01,gameId02,gameId03` + required: true + content: + text/plain: + schema: + type: string + responses: + "200": + description: The stream of the games matching the requested IDs. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/x-ndjson: + schema: + $ref: '../../schemas/GameStream.yaml' diff --git a/doc/specs/tags/games/api-user-username-current-game.yaml b/doc/specs/tags/games/api-user-username-current-game.yaml new file mode 100644 index 0000000..826aeb0 --- /dev/null +++ b/doc/specs/tags/games/api-user-username-current-game.yaml @@ -0,0 +1,105 @@ +get: + operationId: apiUserCurrentGame + summary: Export ongoing game of a user + description: | + Download the ongoing game, or the last game played, of a user. + Available in either PGN or JSON format. + Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: true + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: true + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: true + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: false + - in: query + name: literate + description: | + Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. + Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` + schema: + type: boolean + default: false + - in: query + name: players + description: | + URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. + Example: + 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: '../../schemas/GamePgn.yaml' + application/json: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/games/game-export-gameId.yaml b/doc/specs/tags/games/game-export-gameId.yaml new file mode 100644 index 0000000..7af554c --- /dev/null +++ b/doc/specs/tags/games/game-export-gameId.yaml @@ -0,0 +1,105 @@ +get: + operationId: gamePgn + summary: Export one game + description: | + Download one game in either PGN or JSON format. + Ongoing games are delayed by a few seconds ranging from 3 to 60 depending on the time control, as to prevent cheat bots from using this API. + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: true + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: true + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: true + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: true + - in: query + name: literate + description: | + Insert textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination. + Example: `5... g4? { (-0.98 → 0.60) Mistake. Best move was h6. } (5... h6 6. d4 Ne7 7. g3 d5 8. exd5 fxg3 9. hxg3 c6 10. dxc6)` + schema: + type: boolean + default: false + - in: query + name: players + description: | + URL of a text file containing real names and ratings, to replace Lichess usernames and ratings in the PGN. + Example: + 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: '../../schemas/GamePgn.yaml' + application/json: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/messaging/inbox-username.yaml b/doc/specs/tags/messaging/inbox-username.yaml new file mode 100644 index 0000000..b385e44 --- /dev/null +++ b/doc/specs/tags/messaging/inbox-username.yaml @@ -0,0 +1,41 @@ +post: + operationId: inboxUsername + summary: Send a private message + description: | + Send a private message to another player. + 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: '../../schemas/Ok.yaml' + "400": + description: The sending of the private message has failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/oauth/api-token-test.yaml b/doc/specs/tags/oauth/api-token-test.yaml new file mode 100644 index 0000000..62aff58 --- /dev/null +++ b/doc/specs/tags/oauth/api-token-test.yaml @@ -0,0 +1,50 @@ +post: + operationId: tokenTest + summary: Test multiple OAuth tokens + description: | + For up to 1000 OAuth tokens, + returns their associated user ID and scopes, + or `null` if the token is invalid. + The method is `POST` so a longer list of tokens can be sent in the request body. + 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 + } diff --git a/doc/specs/tags/oauth/api-token.yaml b/doc/specs/tags/oauth/api-token.yaml new file mode 100644 index 0000000..1f18b62 --- /dev/null +++ b/doc/specs/tags/oauth/api-token.yaml @@ -0,0 +1,73 @@ +post: + operationId: apiToken + summary: Obtain access token + tags: + - OAuth + security: [] + description: | + OAuth2 token endpoint. Exchanges an authorization code for an access token. + 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: '../../schemas/OAuthError.yaml' +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: "'*'" diff --git a/doc/specs/tags/oauth/oauth.yaml b/doc/specs/tags/oauth/oauth.yaml new file mode 100644 index 0000000..f6d5f11 --- /dev/null +++ b/doc/specs/tags/oauth/oauth.yaml @@ -0,0 +1,84 @@ +get: + operationId: oauth + summary: Request authorization code + tags: + - OAuth + security: [] + description: | + OAuth2 authorization endpoint. + Start the OAuth2 Authorization Code Flow with PKCE by securely + generating two random strings unique to each authorization + request: + * `code_verifier` + * `state` + Store these in session storage. Make sure not to reveal `code_verifier` + to eavesdroppers. Do not show it in URLs, do not abuse `state` to store + it, do not send it over insecure connections. However it is fine if + the user themselves can extract `code_verifier`, which will always be + possible for fully client-side apps. + Then send the user to this endpoint. They will be prompted to grant + authorization and then be redirected back to the given `redirect_uri`. + If the authorization failed, the following query string parameters will + be appended to the redirection: + * `error`, in particular with value `access_denied` if the user + cancelled authorization + * `error_description` to aid debugging + * `state`, exactly as passed in the `state` parameter + If the authorization succeeded, the following query string parameters + will be appended to the redirection: + * `code`, containing a fresh short-lived authorization code + * `state`, exactly as passed in the `state` parameter + Next, to defend against cross site request forgery, check that the + returned `state` matches the `state` you originally generated. + Finally, continue by using the authorization code to + [obtain an access token](#operation/apiToken). + 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. diff --git a/doc/specs/tags/openingexplorer/lichess.yaml b/doc/specs/tags/openingexplorer/lichess.yaml new file mode 100644 index 0000000..0bd6629 --- /dev/null +++ b/doc/specs/tags/openingexplorer/lichess.yaml @@ -0,0 +1,114 @@ +servers: + - url: https://explorer.lichess.ovh +get: + operationId: openingExplorerLichess + summary: Lichess games + description: | + **Endpoint: ** + Games sampled from all Lichess players. + Example: `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` + tags: + - Opening Explorer + security: [] + parameters: + - in: query + name: variant + description: Variant + schema: + $ref: '../../schemas/VariantKey.yaml' + 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. + Play additional moves starting from `fen`. + Required to find an opening name, if `fen` is not an exact match + for a named position. + 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: '../../schemas/Speed.yaml' + - in: query + name: ratings + description: | + Comma separated list of ratings groups to filter by. + Each group ranges from its value to the next higher + group in the enum (`0` from 0 to 999, `1000` from 1000 to 1199, + ..., `2500` from 2500 to any rating above). + 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 # or 8, depending on query + - 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: '../../schemas/OpeningExplorerJson.yaml' diff --git a/doc/specs/tags/openingexplorer/master-pgn-gameId.yaml b/doc/specs/tags/openingexplorer/master-pgn-gameId.yaml new file mode 100644 index 0000000..3b9a082 --- /dev/null +++ b/doc/specs/tags/openingexplorer/master-pgn-gameId.yaml @@ -0,0 +1,29 @@ +servers: + - url: https://explorer.lichess.ovh +get: + operationId: openingExplorerMasterGame + summary: OTB master game + description: | + **Endpoint: `https://explorer.lichess.ovh/masters/pgn/{gameId}`** + Example: `curl https://explorer.lichess.ovh/masters/pgn/aAbqI4ey` + 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: '../../schemas/MasterGamePgn.yaml' diff --git a/doc/specs/tags/openingexplorer/masters.yaml b/doc/specs/tags/openingexplorer/masters.yaml new file mode 100644 index 0000000..caa2f31 --- /dev/null +++ b/doc/specs/tags/openingexplorer/masters.yaml @@ -0,0 +1,65 @@ +servers: + - url: https://explorer.lichess.ovh +get: + operationId: openingExplorerMaster + summary: Masters database + description: | + **Endpoint: ** + Example: `curl https://explorer.lichess.ovh/masters?play=d2d4,d7d5,c2c4,c7c6,c4d5` + 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. + Play additional moves starting from `fen`. + Required to find an opening name, if `fen` is not an exact match + for a named position. + 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: '../../schemas/OpeningExplorerJson.yaml' diff --git a/doc/specs/tags/openingexplorer/player.yaml b/doc/specs/tags/openingexplorer/player.yaml new file mode 100644 index 0000000..2c7141c --- /dev/null +++ b/doc/specs/tags/openingexplorer/player.yaml @@ -0,0 +1,101 @@ +servers: + - url: https://explorer.lichess.ovh +get: + operationId: openingExplorerPlayer + summary: Player games + description: | + **Endpoint: ** + Games of a Lichess player. + Responds with a stream of [newline delimited JSON](#section/Introduction/Streaming-with-ND-JSON). Will start indexing + on demand, immediately respond with the current results, and stream + more updates until indexing is complete. The stream is throttled + and deduplicated. Empty lines may be sent to avoid timeouts. + Will index new games at most once per minute, and revisit previously + ongoing games at most once every day. + Example: `curl https://explorer.lichess.ovh/player?player=revoof&color=white&play=d2d4,d7d5&recentGames=1` + 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: '../../schemas/VariantKey.yaml' + 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. + Play additional moves starting from `fen`. + Required to find an opening name, if `fen` is not an exact match + for a named position. + 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: '../../schemas/Speed.yaml' + - 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: '../../schemas/OpeningExplorerPlayerJson.yaml' diff --git a/doc/specs/tags/puzzles/api-puzzle-activity.yaml b/doc/specs/tags/puzzles/api-puzzle-activity.yaml new file mode 100644 index 0000000..8036d0d --- /dev/null +++ b/doc/specs/tags/puzzles/api-puzzle-activity.yaml @@ -0,0 +1,36 @@ +get: + operationId: apiPuzzleActivity + summary: Get your puzzle activity + description: | + Download your puzzle activity in [ndjson](#section/Introduction/Streaming-with-ND-JSON) format. + Puzzle activity is sorted by reverse chronological order (most recent first) + We recommend streaming the response, for it can be very long. + 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: '../../schemas/PuzzleRoundJson.yaml' diff --git a/doc/specs/tags/puzzles/api-puzzle-daily.yaml b/doc/specs/tags/puzzles/api-puzzle-daily.yaml new file mode 100644 index 0000000..062519e --- /dev/null +++ b/doc/specs/tags/puzzles/api-puzzle-daily.yaml @@ -0,0 +1,21 @@ +get: + operationId: apiPuzzleDaily + summary: Get the daily puzzle + description: | + Get the daily Lichess puzzle in JSON format. + Alternatively, you can [post it in your slack workspace](https://lichess.org/daily-puzzle-slack). + tags: + - Puzzles + security: [] + responses: + "200": + description: The daily puzzle. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + $ref: '../../schemas/PuzzleAndGame.yaml' diff --git a/doc/specs/tags/puzzles/api-puzzle-dashboard-days.yaml b/doc/specs/tags/puzzles/api-puzzle-dashboard-days.yaml new file mode 100644 index 0000000..c3879e5 --- /dev/null +++ b/doc/specs/tags/puzzles/api-puzzle-dashboard-days.yaml @@ -0,0 +1,31 @@ +get: + operationId: apiPuzzleDashboard + summary: Get your puzzle dashboard + description: | + Download your [puzzle dashboard](https://lichess.org/training/dashboard/30/dashboard) as JSON. + Also includes all puzzle themes played, with aggregated results. + Allows re-creating the [improvement/strengths](https://lichess.org/training/dashboard/30/improvementAreas) interfaces. + 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: '../../schemas/PuzzleDashboardJson.yaml' diff --git a/doc/specs/tags/puzzles/api-puzzle-id.yaml b/doc/specs/tags/puzzles/api-puzzle-id.yaml new file mode 100644 index 0000000..079c382 --- /dev/null +++ b/doc/specs/tags/puzzles/api-puzzle-id.yaml @@ -0,0 +1,26 @@ +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: '../../schemas/PuzzleAndGame.yaml' diff --git a/doc/specs/tags/puzzles/api-racer.yaml b/doc/specs/tags/puzzles/api-racer.yaml new file mode 100644 index 0000000..1d3a137 --- /dev/null +++ b/doc/specs/tags/puzzles/api-racer.yaml @@ -0,0 +1,24 @@ +post: + operationId: racerPost + summary: Create and join a puzzle race + description: | + Create a new private [puzzle race](https://lichess.org/racer). + The Lichess user who creates the race must join the race page, + and manually start the race when enough players have joined. + - + 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: '../../schemas/PuzzleRaceJson.yaml' diff --git a/doc/specs/tags/puzzles/api-storm-dashboard-username.yaml b/doc/specs/tags/puzzles/api-storm-dashboard-username.yaml new file mode 100644 index 0000000..2ab27dd --- /dev/null +++ b/doc/specs/tags/puzzles/api-storm-dashboard-username.yaml @@ -0,0 +1,37 @@ +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. + Contains the aggregated highscores, and the history of storm runs aggregated by days. + Use `?days=0` if you only care about the highscores. + 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: '../../schemas/StormDashboardJson.yaml' diff --git a/doc/specs/tags/relations/api-rel-follow-username.yaml b/doc/specs/tags/relations/api-rel-follow-username.yaml new file mode 100644 index 0000000..903c034 --- /dev/null +++ b/doc/specs/tags/relations/api-rel-follow-username.yaml @@ -0,0 +1,23 @@ +post: + operationId: followUser + summary: Follow a player + description: | + Follow a player, adding them to your list of Lichess friends. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/relations/api-rel-following.yaml b/doc/specs/tags/relations/api-rel-following.yaml new file mode 100644 index 0000000..ad79fe9 --- /dev/null +++ b/doc/specs/tags/relations/api-rel-following.yaml @@ -0,0 +1,21 @@ +get: + operationId: apiUserFollowing + summary: Get users followed by the logged in user + description: | + Users are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/UserExtended.yaml' diff --git a/doc/specs/tags/relations/api-rel-unfollow-username.yaml b/doc/specs/tags/relations/api-rel-unfollow-username.yaml new file mode 100644 index 0000000..7b380ab --- /dev/null +++ b/doc/specs/tags/relations/api-rel-unfollow-username.yaml @@ -0,0 +1,23 @@ +post: + operationId: unfollowUser + summary: Unfollow a player + description: | + Unfollow a player, removing them from your list of Lichess friends. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/simuls/api-simul.yaml b/doc/specs/tags/simuls/api-simul.yaml new file mode 100644 index 0000000..772f167 --- /dev/null +++ b/doc/specs/tags/simuls/api-simul.yaml @@ -0,0 +1,40 @@ +get: + operationId: apiSimul + summary: Get current simuls + description: | + Get recently created, started, finished, simuls. + Created and finished simul lists are not exhaustives, only those with + strong enough host will be listed, the same filter is used to display simuls on https://lichess.org/simul. + When [authenticated with OAuth2](#section/Introduction/Authentication), the pending list will be populated with your created, but unstarted simuls. + tags: + - Simuls + security: [] + responses: + "200": + description: The list of simuls. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/json: + schema: + type: object + properties: + pending: + type: array + items: + $ref: '../../schemas/Simul.yaml' + created: + type: array + items: + $ref: '../../schemas/Simul.yaml' + started: + type: array + items: + $ref: '../../schemas/Simul.yaml' + finished: + type: array + items: + $ref: '../../schemas/Simul.yaml' diff --git a/doc/specs/tags/studies/api-study-by-username.yaml b/doc/specs/tags/studies/api-study-by-username.yaml new file mode 100644 index 0000000..a9306b5 --- /dev/null +++ b/doc/specs/tags/studies/api-study-by-username.yaml @@ -0,0 +1,33 @@ +get: + operationId: studyListMetadata + summary: List studies of a user + description: | + Get metadata (name and dates) of all studies of a user. + If authenticated, then all public, unlisted, and private studies are included. + If not, only public (non-unlisted) studies are included. + Studies are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/StudyMetadata.yaml' diff --git a/doc/specs/tags/studies/api-study-studyId-chapterId.pgn.yaml b/doc/specs/tags/studies/api-study-studyId-chapterId.pgn.yaml new file mode 100644 index 0000000..6cedaee --- /dev/null +++ b/doc/specs/tags/studies/api-study-studyId-chapterId.pgn.yaml @@ -0,0 +1,68 @@ +get: + operationId: studyChapterPgn + summary: Export one study chapter + description: | + Download one study chapter in PGN format. + 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. + Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + schema: + type: boolean + default: true + - in: query + name: comments + description: | + Include analysis and annotator comments in the PGN moves, when available. + Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` + schema: + type: boolean + default: true + - in: query + name: variations + description: | + Include non-mainline moves, when available. + Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` + schema: + type: boolean + default: true + - in: query + name: source + description: | + Add a `Source` PGN tag with the study chapter URL. + Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` + schema: + type: boolean + default: false + - in: query + name: orientation + description: | + Add a `Orientation` PGN tag with the chapter predefined orientation. + Example: `[Orientation "white"]` + schema: + type: boolean + default: false + responses: + "200": + description: The chapter of the study. + content: + application/x-chess-pgn: + schema: + $ref: '../../schemas/StudyPgn.yaml' diff --git a/doc/specs/tags/studies/api-study-studyId-import-pgn.yaml b/doc/specs/tags/studies/api-study-studyId-import-pgn.yaml new file mode 100644 index 0000000..564b0cd --- /dev/null +++ b/doc/specs/tags/studies/api-study-studyId-import-pgn.yaml @@ -0,0 +1,68 @@ +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. + If the PGN contains multiple games (separated by 2 or more newlines) + then multiple chapters will be created within the study. + Note that a study can contain at most 64 chapters. + 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. + If multiple chapters are created, the names will be infered from the PGN tags. + minLength: 1 + maxLength: 100 + pgn: + type: string + description: | + PGN to import. Can contain multiple games separated by 2 or more newlines. + orientation: + type: string + description: Default board orientation. + enum: + - white + - black + default: white + variant: + $ref: '../../schemas/VariantKey.yaml' + 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: '../../schemas/StudyImportPgnChapters.yaml' + "400": + description: The creation of the Swiss tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/studies/api-study-studyId.pgn.yaml b/doc/specs/tags/studies/api-study-studyId.pgn.yaml new file mode 100644 index 0000000..05b1608 --- /dev/null +++ b/doc/specs/tags/studies/api-study-studyId.pgn.yaml @@ -0,0 +1,98 @@ +get: + operationId: studyAllChaptersPgn + summary: Export all chapters + description: | + Download all chapters of a study in PGN format. + 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. + Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + schema: + type: boolean + default: true + - in: query + name: comments + description: | + Include analysis and annotator comments in the PGN moves, when available. + Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` + schema: + type: boolean + default: true + - in: query + name: variations + description: | + Include non-mainline moves, when available. + Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` + schema: + type: boolean + default: true + - in: query + name: source + description: | + Add a `Source` PGN tag with the study chapter URL. + Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` + schema: + type: boolean + default: false + - in: query + name: orientation + description: | + Add a `Orientation` PGN tag with the chapter predefined orientation. + Example: `[Orientation "white"]` + 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: '../../schemas/StudyPgn.yaml' +head: + operationId: studyAllChaptersHead + summary: Study metadata + description: | + Only get the study headers, including `Last-Modified`. + 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' diff --git a/doc/specs/tags/studies/study-by-username-export.pgn.yaml b/doc/specs/tags/studies/study-by-username-export.pgn.yaml new file mode 100644 index 0000000..b5fbe57 --- /dev/null +++ b/doc/specs/tags/studies/study-by-username-export.pgn.yaml @@ -0,0 +1,65 @@ +get: + operationId: studyExportAllPgn + summary: Export all studies of a user + description: | + Download all chapters of all studies of a user in PGN format. + If authenticated, then all public, unlisted, and private studies are included. + If not, only public (non-unlisted) studies are included. + 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. + Example: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + schema: + type: boolean + default: true + - in: query + name: comments + description: | + Include analysis and annotator comments in the PGN moves, when available. + Example: `12. Bxf6 { [%eval 0.23] } a3 { White is in a pickle. }` + schema: + type: boolean + default: true + - in: query + name: variations + description: | + Include non-mainline moves, when available. + Example: `4. d4 Bb4+ (4... Nc6 5. Nf3 Bb4+ 6. Bd2 (6. Nbd2 O-O 7. O-O) 6... Bd6) 5. Nd2` + schema: + type: boolean + default: true + - in: query + name: source + description: | + Add a `Source` PGN tag with the study chapter URL. + Example: `[Source "https://lichess.org/study/4NBHImfM/1Tk4IyTz"]` + schema: + type: boolean + default: false + - in: query + name: orientation + description: | + Add a `Orientation` PGN tag with the chapter predefined orientation. + Example: `[Orientation "white"]` + schema: + type: boolean + default: false + responses: + "200": + description: The studies of the user. + content: + application/x-chess-pgn: + schema: + $ref: '../../schemas/StudyPgn.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-edit.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-edit.yaml new file mode 100644 index 0000000..c5621a7 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-edit.yaml @@ -0,0 +1,201 @@ +post: + operationId: apiSwissUpdate + summary: Update a Swiss tournament + description: | + Update a Swiss tournament. + Be mindful not to make important changes to ongoing tournaments. + Additional restrictions: + - clock.limit + clock.increment > 0 + - 15s and 0+1 variant tournaments cannot be rated + 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. + Set to 99999999 to manually schedule each round from the tournament UI, or [with the API](#tag/Swiss-tournaments/operation/apiSwissScheduleNextRound). + If empty or -1, a sensible value is picked automatically. + enum: + - -1 + - 5 + - 10 + - 20 + - 30 + - 45 + - 60 + - 120 + - 180 + - 300 + - 600 + - 900 + - 1200 + - 1800 + - 2700 + - 3600 + - 86400 + - 172800 + - 604800 + - 99999999 + variant: + $ref: '../../schemas/VariantKey.yaml' + 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. + Two usernames per line, separated by a space. + manualPairings: + type: string + description: | + Manual pairings for the next round. + Two usernames per line, separated by a space. + Present players without a valid pairing will be given a bye, which is worth 1 point. + Forfeited players will get 0 points. + chatFor: + type: number + description: | + Who can read and write in the chat. + - 0 = No-one + - 10 = Only team leaders + - 20 = Only team members + - 30 = All Lichess players + 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. + If they failed to show up in a recent swiss event, they won't be able to enter yours. + This results in a better swiss experience for the players who actually show up. + default: false + conditions.allowList: + type: string + description: | + Predefined list of usernames that are allowed to join, separated by commas. + If this list is non-empty, then usernames absent from this list will be forbidden to join. + Adding `%titled` to the list additionally allows any titled player to join. + Example: `thibault,german11,%titled` + 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: '../../schemas/SwissTournament.yaml' + "400": + description: Updating the swiss failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' + "401": + description: This user cannot update this Swiss. + content: + application/json: + schema: + $ref: '../../schemas/SwissUnauthorisedEdit.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-games.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-games.yaml new file mode 100644 index 0000000..0865508 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-games.yaml @@ -0,0 +1,98 @@ +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. + Games are sorted by reverse chronological order (last round first). + The game stream is throttled, depending on who is making the request: + - Anonymous request: 20 games per second + - [OAuth2 authenticated](#section/Introduction/Authentication) request: 30 games per second + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: evals + description: | + Include analysis evaluations and comments, when available. + Either as PGN comments: `12. Bxf6 { [%eval 0.23] } a3 { [%eval -1.09] }` + Or in an `analysis` JSON field, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: accuracy + description: | + Include [accuracy percent](https://lichess.org/page/accuracy) of each player, when available. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: false + - in: query + name: division + description: | + Plies which mark the beginning of the middlegame and endgame. + Only available in JSON + schema: + type: boolean + default: false + 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: '../../schemas/GamePgn.yaml' + application/x-ndjson: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-join.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-join.yaml new file mode 100644 index 0000000..c5f8202 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-join.yaml @@ -0,0 +1,46 @@ +post: + operationId: apiSwissJoin + summary: Join a Swiss tournament + description: | + Join a Swiss tournament, possibly with a password. + 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: '../../schemas/Ok.yaml' + "400": + description: Joining the tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-results.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-results.yaml new file mode 100644 index 0000000..f7ad3de --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-results.yaml @@ -0,0 +1,45 @@ +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). + Players are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + If called on an ongoing tournament, results can be inconsistent + due to ranking changes while the players are being streamed. + Use on finished tournaments for guaranteed consistency. + 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 + } diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-schedule-next-round.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-schedule-next-round.yaml new file mode 100644 index 0000000..9443752 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-schedule-next-round.yaml @@ -0,0 +1,50 @@ +post: + operationId: apiSwissScheduleNextRound + summary: Manually schedule the next round + description: | + Manually schedule the next round date and time of a Swiss tournament. + This sets the `roundInterval` field to `99999999`, i.e. manual scheduling. + All further rounds will need to be manually scheduled, unless the `roundInterval` field is changed back to automatic scheduling. + 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: '../../schemas/Error.yaml' + "401": + description: This user cannot update this Swiss. + content: + application/json: + schema: + $ref: '../../schemas/SwissUnauthorisedEdit.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-terminate.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-terminate.yaml new file mode 100644 index 0000000..26c0979 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-terminate.yaml @@ -0,0 +1,35 @@ +post: + operationId: apiSwissTerminate + summary: Terminate a Swiss tournament + description: | + Terminate a Swiss tournament + 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: '../../schemas/Ok.yaml' + "400": + description: Terminating the Swiss tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id-withdraw.yaml b/doc/specs/tags/swisstournaments/api-swiss-id-withdraw.yaml new file mode 100644 index 0000000..c700556 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id-withdraw.yaml @@ -0,0 +1,30 @@ +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. + It's possible to join again later. Points are preserved. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-id.yaml b/doc/specs/tags/swisstournaments/api-swiss-id.yaml new file mode 100644 index 0000000..783c0b2 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-id.yaml @@ -0,0 +1,27 @@ +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. + 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: '../../schemas/SwissTournament.yaml' diff --git a/doc/specs/tags/swisstournaments/api-swiss-new-teamId.yaml b/doc/specs/tags/swisstournaments/api-swiss-new-teamId.yaml new file mode 100644 index 0000000..fd2ba16 --- /dev/null +++ b/doc/specs/tags/swisstournaments/api-swiss-new-teamId.yaml @@ -0,0 +1,204 @@ +post: + operationId: apiSwissNew + summary: Create a new Swiss tournament + description: | + Create a Swiss tournament for your team. + This endpoint mirrors the Swiss tournament form from your team pagee. + You can create up to 12 tournaments per day. + Additional restrictions: + - clock.limit + clock.increment > 0 + - 15s and 0+1 variant tournaments cannot be rated + 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. + Set to 99999999 to manually schedule each round from the tournament UI. + If empty or -1, a sensible value is picked automatically. + enum: + - -1 + - 5 + - 10 + - 20 + - 30 + - 45 + - 60 + - 120 + - 180 + - 300 + - 600 + - 900 + - 1200 + - 1800 + - 2700 + - 3600 + - 86400 + - 172800 + - 604800 + - 99999999 + variant: + $ref: '../../schemas/VariantKey.yaml' + position: + $ref: '../../schemas/FromPositionFEN.yaml' + 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. + Two usernames per line, separated by a space. + manualPairings: + type: string + description: | + Manual pairings for the next round. + Two usernames per line, separated by a space. Example: + ``` + PlayerA PlayerB + PlayerC PlayerD + ``` + To give a bye (1 point) to a player instead of a pairing, add a line like so: + ``` + PlayerE 1 + ``` + Missing players will be considered absent and get zero points. + chatFor: + type: number + description: | + Who can read and write in the chat. + - 0 = No-one + - 10 = Only team leaders + - 20 = Only team members + - 30 = All Lichess players + 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. + If they failed to show up in a recent swiss event, they won't be able to enter yours. + This results in a better swiss experience for the players who actually show up. + default: false + conditions.allowList: + type: string + description: | + Predefined list of usernames that are allowed to join, separated by commas. + If this list is non-empty, then usernames absent from this list will be forbidden to join. + Adding `%titled` to the list additionally allows any titled player to join. + Example: `thibault,german11,%titled` + 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: '../../schemas/SwissTournament.yaml' + "400": + description: The creation of the Swiss tournament failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/swisstournaments/swiss-id.trf.yaml b/doc/specs/tags/swisstournaments/swiss-id.trf.yaml new file mode 100644 index 0000000..9cd91a4 --- /dev/null +++ b/doc/specs/tags/swisstournaments/swiss-id.trf.yaml @@ -0,0 +1,29 @@ +get: + operationId: swissTrf + summary: Export TRF of a Swiss tournament + description: | + Download a tournament in the Tournament Report File format, the FIDE standard. + Documentation: + Example: + 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 diff --git a/doc/specs/tags/tablebase/antichess.yaml b/doc/specs/tags/tablebase/antichess.yaml new file mode 100644 index 0000000..031c502 --- /dev/null +++ b/doc/specs/tags/tablebase/antichess.yaml @@ -0,0 +1,22 @@ +servers: + - url: https://tablebase.lichess.ovh +get: + operationId: antichessAtomic + summary: Tablebase lookup for Antichess + description: | + **Endpoint: ** + 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: "'*'" diff --git a/doc/specs/tags/tablebase/atomic.yaml b/doc/specs/tags/tablebase/atomic.yaml new file mode 100644 index 0000000..a484247 --- /dev/null +++ b/doc/specs/tags/tablebase/atomic.yaml @@ -0,0 +1,22 @@ +servers: + - url: https://tablebase.lichess.ovh +get: + operationId: tablebaseAtomic + summary: Tablebase lookup for Atomic chess + description: | + **Endpoint: ** + 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: "'*'" diff --git a/doc/specs/tags/tablebase/standard.yaml b/doc/specs/tags/tablebase/standard.yaml new file mode 100644 index 0000000..0f8e585 --- /dev/null +++ b/doc/specs/tags/tablebase/standard.yaml @@ -0,0 +1,30 @@ +servers: + - url: https://tablebase.lichess.ovh +get: + operationId: tablebaseStandard + summary: Tablebase lookup + description: | + **Endpoint: ** + Example: `curl http://tablebase.lichess.ovh/standard?fen=4k3/6KP/8/8/8/8/7p/8_w_-_-_0_1` + 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: '../../schemas/TablebaseJson.yaml' diff --git a/doc/specs/tags/teams/api-team-all.yaml b/doc/specs/tags/teams/api-team-all.yaml new file mode 100644 index 0000000..dce6497 --- /dev/null +++ b/doc/specs/tags/teams/api-team-all.yaml @@ -0,0 +1,27 @@ +get: + operationId: teamAll + summary: Get popular teams + description: | + Paginator of the most popular teams. + 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: '../../schemas/TeamPaginatorJson.yaml' diff --git a/doc/specs/tags/teams/api-team-of-username.yaml b/doc/specs/tags/teams/api-team-of-username.yaml new file mode 100644 index 0000000..273f346 --- /dev/null +++ b/doc/specs/tags/teams/api-team-of-username.yaml @@ -0,0 +1,29 @@ +get: + operationId: teamOfUsername + summary: Teams of a player + description: | + All the teams a player is a member of. + 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: '../../schemas/Team.yaml' diff --git a/doc/specs/tags/teams/api-team-search.yaml b/doc/specs/tags/teams/api-team-search.yaml new file mode 100644 index 0000000..d174b21 --- /dev/null +++ b/doc/specs/tags/teams/api-team-search.yaml @@ -0,0 +1,32 @@ +get: + operationId: teamSearch + summary: Search teams + description: | + Paginator of team search results for a keyword. + 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: '../../schemas/TeamPaginatorJson.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-arena.yaml b/doc/specs/tags/teams/api-team-teamId-arena.yaml new file mode 100644 index 0000000..aef4a8d --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-arena.yaml @@ -0,0 +1,37 @@ +get: + operationId: apiTeamArena + summary: Get team Arena tournaments + description: | + Get all Arena tournaments relevant to a team. + Tournaments are sorted by reverse chronological order of start date (last starting first). + Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/ArenaTournament.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-kick-userId.yaml b/doc/specs/tags/teams/api-team-teamId-kick-userId.yaml new file mode 100644 index 0000000..19b6168 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-kick-userId.yaml @@ -0,0 +1,30 @@ +post: + operationId: teamIdKickUserId + summary: Kick a user from your team + description: | + Kick a member out of one of your teams. + - + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-request-userId-accept.yaml b/doc/specs/tags/teams/api-team-teamId-request-userId-accept.yaml new file mode 100644 index 0000000..c140c01 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-request-userId-accept.yaml @@ -0,0 +1,28 @@ +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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-request-userId-decline.yaml b/doc/specs/tags/teams/api-team-teamId-request-userId-decline.yaml new file mode 100644 index 0000000..949d388 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-request-userId-decline.yaml @@ -0,0 +1,28 @@ +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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-requests.yaml b/doc/specs/tags/teams/api-team-teamId-requests.yaml new file mode 100644 index 0000000..ddbae47 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-requests.yaml @@ -0,0 +1,72 @@ +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: '../../schemas/TeamRequestWithUser.yaml' + 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" + } + } +] diff --git a/doc/specs/tags/teams/api-team-teamId-swiss.yaml b/doc/specs/tags/teams/api-team-teamId-swiss.yaml new file mode 100644 index 0000000..ce56ff1 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-swiss.yaml @@ -0,0 +1,37 @@ +get: + operationId: apiTeamSwiss + summary: Get team swiss tournaments + description: | + Get all swiss tournaments of a team. + Tournaments are sorted by reverse chronological order of start date (last starting first). + Tournaments are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/SwissTournament.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId-users.yaml b/doc/specs/tags/teams/api-team-teamId-users.yaml new file mode 100644 index 0000000..aab4664 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId-users.yaml @@ -0,0 +1,30 @@ +get: + operationId: teamIdUsers + summary: Get members of a team + description: | + Members are sorted by reverse chronological order of joining the team (most recent first). + OAuth is only required if the list of members is private. + Members are streamed as [ndjson](#section/Introduction/Streaming-with-ND-JSON). + 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: '../../schemas/UserExtended.yaml' diff --git a/doc/specs/tags/teams/api-team-teamId.yaml b/doc/specs/tags/teams/api-team-teamId.yaml new file mode 100644 index 0000000..5a02281 --- /dev/null +++ b/doc/specs/tags/teams/api-team-teamId.yaml @@ -0,0 +1,25 @@ +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: '../../schemas/Team.yaml' diff --git a/doc/specs/tags/teams/team-teamId-join.yaml b/doc/specs/tags/teams/team-teamId-join.yaml new file mode 100644 index 0000000..a2437db --- /dev/null +++ b/doc/specs/tags/teams/team-teamId-join.yaml @@ -0,0 +1,41 @@ +post: + operationId: teamIdJoin + summary: Join a team + description: | + Join a team. + If the team requires a password but the `password` field is incorrect, + then the call fails with `403 Forbidden`. + Similarly, if the team join policy requires a confirmation but the + `message` parameter is not given, then the call fails with + `403 Forbidden`. + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/teams/team-teamId-pm-all.yaml b/doc/specs/tags/teams/team-teamId-pm-all.yaml new file mode 100644 index 0000000..47da5d6 --- /dev/null +++ b/doc/specs/tags/teams/team-teamId-pm-all.yaml @@ -0,0 +1,45 @@ +post: + operationId: teamIdPmAll + summary: Message all members + description: | + Send a private message to all members of a team. + You must be a team leader with the "Messages" permission. + 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: '../../schemas/Ok.yaml' + "400": + description: The sending of message to all team members has failed. + content: + application/json: + schema: + $ref: '../../schemas/Error.yaml' diff --git a/doc/specs/tags/teams/team-teamId-quit.yaml b/doc/specs/tags/teams/team-teamId-quit.yaml new file mode 100644 index 0000000..c1ab5cb --- /dev/null +++ b/doc/specs/tags/teams/team-teamId-quit.yaml @@ -0,0 +1,24 @@ +post: + operationId: teamIdQuit + summary: Leave a team + description: | + Leave a team. + - + 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: '../../schemas/Ok.yaml' diff --git a/doc/specs/tags/tv/api-tv-channel.yaml b/doc/specs/tags/tv/api-tv-channel.yaml new file mode 100644 index 0000000..c752484 --- /dev/null +++ b/doc/specs/tags/tv/api-tv-channel.yaml @@ -0,0 +1,69 @@ +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). + Available in PGN or [ndjson](#section/Introduction/Streaming-with-ND-JSON) format, depending on the request `Accept` header. + 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. + Either as PGN comments: `2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }` + Or in a `clocks` JSON field, as centisecond integers, depending on the response type. + schema: + type: boolean + default: false + - in: query + name: opening + description: | + Include the opening name. + Example: `[Opening "King's Gambit Accepted, King's Knight Gambit"]` + schema: + type: boolean + default: false + responses: + "200": + description: The representation of the games. + content: + application/x-chess-pgn: + schema: + $ref: '../../schemas/GamePgn.yaml' + application/x-ndjson: + schema: + $ref: '../../schemas/GameJson.yaml' diff --git a/doc/specs/tags/tv/api-tv-channels.yaml b/doc/specs/tags/tv/api-tv-channels.yaml new file mode 100644 index 0000000..fff4161 --- /dev/null +++ b/doc/specs/tags/tv/api-tv-channels.yaml @@ -0,0 +1,114 @@ +get: + operationId: tvChannels + summary: Get current TV games + description: | + Get basic info about the best games being played for each speed and variant, + but also computer games and bot games. + See [lichess.org/tv](https://lichess.org/tv). + 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" + } + } diff --git a/doc/specs/tags/tv/api-tv-feed.yaml b/doc/specs/tags/tv/api-tv-feed.yaml new file mode 100644 index 0000000..e5121f2 --- /dev/null +++ b/doc/specs/tags/tv/api-tv-feed.yaml @@ -0,0 +1,36 @@ +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). + A summary of the game is sent as a first message, and when the featured game changes. + Try it with `curl https://lichess.org/api/tv/feed`. + tags: + - TV + security: [] + responses: + "200": + description: The stream of the current TV game. + content: + application/x-ndjson: + schema: + example: { + "t": "featured", + "d": { + "id": "qVSOPtMc", + "orientation": "black", + "players": [ + { + "color": "white", + "user": { "name": "lizen9", "id": "lizen9", "title": "GM" }, + "rating": 2531 + }, + { + "color": "black", + "user": { "name": "lizen29", "title": "WGM", "id": "lizen29" }, + "rating": 2594 + } + ], + "fen": "rnbqk1r1/ppp1ppbp/8/N2p2p1/8/1PQPP3/P1P2PPn/R1B1K1NR" + } + } diff --git a/doc/specs/tags/users/api-crosstable-user1-user2.yaml b/doc/specs/tags/users/api-crosstable-user1-user2.yaml new file mode 100644 index 0000000..02853fa --- /dev/null +++ b/doc/specs/tags/users/api-crosstable-user1-user2.yaml @@ -0,0 +1,37 @@ +get: + operationId: apiCrosstable + summary: Get crosstable + description: | + Get total number of games, and current score, of any two users. + If the `matchup` flag is provided, and the users are currently playing, also gets the current match game number and scores. + 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: '../../schemas/Crosstable.yaml' diff --git a/doc/specs/tags/users/api-player-autocomplete.yaml b/doc/specs/tags/users/api-player-autocomplete.yaml new file mode 100644 index 0000000..fb8b32e --- /dev/null +++ b/doc/specs/tags/users/api-player-autocomplete.yaml @@ -0,0 +1,52 @@ +get: + operationId: apiPlayerAutocomplete + summary: Autocomplete usernames + description: | + Provides autocompletion options for an incomplete username. + 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 + - `true` returns an object with matching users + schema: + type: boolean + default: false + - in: query + name: friend + description: | + Returns followed players matching `term` if any, else returns other players. + Requires [OAuth](#tag/OAuth). + 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: '../../schemas/LightUserOnline.yaml' diff --git a/doc/specs/tags/users/api-player-top-nb-perfType.yaml b/doc/specs/tags/users/api-player-top-nb-perfType.yaml new file mode 100644 index 0000000..878644b --- /dev/null +++ b/doc/specs/tags/users/api-player-top-nb-perfType.yaml @@ -0,0 +1,53 @@ +get: + operationId: playerTopNbPerfType + summary: Get one leaderboard + tags: + - Users + security: [] + description: | + Get the leaderboard for a single speed or variant (a.k.a. `perfType`). + There is no leaderboard for correspondence or puzzles. + See . + 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: '../../schemas/Leaderboard.yaml' diff --git a/doc/specs/tags/users/api-player.yaml b/doc/specs/tags/users/api-player.yaml new file mode 100644 index 0000000..b479e31 --- /dev/null +++ b/doc/specs/tags/users/api-player.yaml @@ -0,0 +1,21 @@ +get: + operationId: player + summary: Get all top 10 + tags: + - Users + security: [] + description: | + Get the top 10 players for each speed and variant. + See . + 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: '../../schemas/Top10s.yaml' diff --git a/doc/specs/tags/users/api-streamer-live.yaml b/doc/specs/tags/users/api-streamer-live.yaml new file mode 100644 index 0000000..e83dfe1 --- /dev/null +++ b/doc/specs/tags/users/api-streamer-live.yaml @@ -0,0 +1,46 @@ +get: + operationId: streamerLive + summary: Get live streamers + description: | + Get basic info about currently streaming users. + This API is very fast and cheap on lichess side. + So you can call it quite often (like once every 5 seconds). + 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: '../../schemas/LightUser.yaml' + 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" + } + } + ] diff --git a/doc/specs/tags/users/api-user-username-activity.yaml b/doc/specs/tags/users/api-user-username-activity.yaml new file mode 100644 index 0000000..8750bdf --- /dev/null +++ b/doc/specs/tags/users/api-user-username-activity.yaml @@ -0,0 +1,26 @@ +get: + operationId: apiUserActivity + summary: Get user activity + description: | + Read data to generate the activity feed of a user. + 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 diff --git a/doc/specs/tags/users/api-user-username-note.yaml b/doc/specs/tags/users/api-user-username-note.yaml new file mode 100644 index 0000000..d0f6650 --- /dev/null +++ b/doc/specs/tags/users/api-user-username-note.yaml @@ -0,0 +1,82 @@ +post: + operationId: writeNote + summary: Add a note for a user + description: | + Add a private note available only to you about this account. + 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: '../../schemas/Ok.yaml' +get: + operationId: readNote + summary: Get notes for a user + description: | + Get the private notes that you have added for a user. + 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: '../../schemas/UserNote.yaml' + 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 + } + ] diff --git a/doc/specs/tags/users/api-user-username-perf-perf.yaml b/doc/specs/tags/users/api-user-username-perf-perf.yaml new file mode 100644 index 0000000..3c25268 --- /dev/null +++ b/doc/specs/tags/users/api-user-username-perf-perf.yaml @@ -0,0 +1,32 @@ +get: + operationId: apiUserPerf + summary: Get performance statistics of a user + description: | + Read performance statistics of a user, for a single performance. + Similar to the [performance pages on the website](https://lichess.org/@/thibault/perf/bullet). + tags: + - Users + security: [] + parameters: + - in: path + name: username + schema: + type: string + required: true + - in: path + name: perf + schema: + $ref: '../../schemas/PerfType.yaml' + 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: '../../schemas/PerfStat.yaml' diff --git a/doc/specs/tags/users/api-user-username-rating-history.yaml b/doc/specs/tags/users/api-user-username-rating-history.yaml new file mode 100644 index 0000000..fb3b38d --- /dev/null +++ b/doc/specs/tags/users/api-user-username-rating-history.yaml @@ -0,0 +1,29 @@ +get: + operationId: apiUserRatingHistory + summary: Get rating history of a user + description: | + Read rating history of a user, for all perf types. + There is at most one entry per day. + Format of an entry is `[year, month, day, rating]`. + `month` starts at zero (January). + 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: '../../schemas/RatingHistory.yaml' diff --git a/doc/specs/tags/users/api-user-username.yaml b/doc/specs/tags/users/api-user-username.yaml new file mode 100644 index 0000000..cc029e5 --- /dev/null +++ b/doc/specs/tags/users/api-user-username.yaml @@ -0,0 +1,35 @@ +get: + operationId: apiUser + summary: Get user public data + description: | + Read public data of a user. + If the request is [authenticated with OAuth2](#section/Introduction/Authentication), + then extra fields might be present in the response: `followable`, `following`, `blocking`, `followsYou`. + 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: '../../schemas/UserExtended.yaml' diff --git a/doc/specs/tags/users/api-users-status.yaml b/doc/specs/tags/users/api-users-status.yaml new file mode 100644 index 0000000..fbce269 --- /dev/null +++ b/doc/specs/tags/users/api-users-status.yaml @@ -0,0 +1,75 @@ +get: + operationId: apiUsersStatus + summary: Get real-time users status + description: | + Read the `online`, `playing` and `streaming` flags of several users. + This API is very fast and cheap on lichess side. + So you can call it quite often (like once every 5 seconds). + Use it to track players and know when they're connected on lichess and playing games. + 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. + Defaults to `false` to preserve server resources. + 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 + } + ] diff --git a/doc/specs/tags/users/api-users.yaml b/doc/specs/tags/users/api-users.yaml new file mode 100644 index 0000000..dba4327 --- /dev/null +++ b/doc/specs/tags/users/api-users.yaml @@ -0,0 +1,34 @@ +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. + The method is `POST` to allow a longer list of IDs to be sent in the request body. + Please do not try to download all the Lichess users with this endpoint, or any other endpoint. + An API is not a way to fully export a website. We do not provide a full download of the Lichess users. + This endpoint is limited to 8,000 users every 10 minutes, and 120,000 every day. + 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: '../../schemas/User.yaml' diff --git a/doc/spectral.yaml b/doc/spectral.yaml index 84061e7..95cfcaa 100644 --- a/doc/spectral.yaml +++ b/doc/spectral.yaml @@ -1,2 +1,8 @@ extends: spectral:oas formats: [ oas3.1 ] +overrides: + - files: + - "specs/lichess-api.yaml#/components/schemas" + - "specs/lichess-api.yaml#/components/examples" + rules: + oas3-unused-component: "off"