{"openapi":"3.1.0","info":{"title":"Lichess Community (BYOK) API","version":"0.1.0","description":"Lichess Community (BYOK) lets an AI assistant read your own Lichess Community data through the Lichess Community API with a key you supply (personal API token (no scopes are needed for these read tools)). Read-only: 12 tools (get_top_leaderboards, get_tv_channels, list_current_tournaments, get_arena_tournament, list_simuls, list_top_broadcasts, get_fide_player, search_fide_players, get_puzzle,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-lichess-community.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-lichess-community/docs"},"termsOfService":"https://connectorbay.com/byok-lichess-community/terms"},"servers":[{"url":"https://byok-lichess-community.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-lichess-community/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_top_leaderboards":{"post":{"operationId":"get_top_leaderboards","summary":"Get the top 10 players for each speed and variant (bullet, blitz, rapid, classical, chess960 and others) with title, pat","description":"Get the top 10 players for each speed and variant (bullet, blitz, rapid, classical, chess960 and others) with title, patron and online flags and ratings. Use for \"Who are the top 10 blitz players on Lichess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_top_leaderboardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_tv_channels":{"post":{"operationId":"get_tv_channels","summary":"Get the best game being played right now for each speed and variant (including computer and bot games): player, rating, ","description":"Get the best game being played right now for each speed and variant (including computer and bot games): player, rating, game id and the colour shown. Use for \"What is the featured blitz game on Lichess TV right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_tv_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_current_tournaments":{"post":{"operationId":"list_current_tournaments","summary":"List recently created, started and finished Lichess arena tournaments with variant, time control, player count and start","description":"List recently created, started and finished Lichess arena tournaments with variant, time control, player count and start and finish times (epoch milliseconds). Use for \"Which arena tournaments are starting soon on Lichess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_current_tournamentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_arena_tournament":{"post":{"operationId":"get_arena_tournament","summary":"Get one arena tournament by id: name, time control, rated flag, schedule, number of players, creator, state and entry co","description":"Get one arena tournament by id: name, time control, rated flag, schedule, number of players, creator, state and entry conditions (player standings are left out). Use for \"Show details of Lichess arena tournament abcd1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tournament_id":{"description":"Arena tournament id from the tournament URL or list_current_tournaments, for example 'abcd1234'.","maxLength":20,"title":"Tournament Id","type":"string"}},"required":["tournament_id"],"title":"get_arena_tournamentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_simuls":{"post":{"operationId":"list_simuls","summary":"List current simultaneous exhibitions (simuls): pending, created, started and finished ones with host, variants and appl","description":"List current simultaneous exhibitions (simuls): pending, created, started and finished ones with host, variants and applicant counts. Use for \"Which chess simuls are running on Lichess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_simulsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_top_broadcasts":{"post":{"operationId":"list_top_broadcasts","summary":"List top live and upcoming broadcasts of over-the-board events as shown on lichess.org/broadcast: tournament, round, sta","description":"List top live and upcoming broadcasts of over-the-board events as shown on lichess.org/broadcast: tournament, round, start times and links. Use for \"Which chess broadcasts are live on Lichess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, 1 to 20; only page 1 has active broadcasts.","title":"Page"}},"title":"list_top_broadcastsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_fide_player":{"post":{"operationId":"get_fide_player","summary":"Get a FIDE player by FIDE id: name, title, federation, birth year, standard, rapid and blitz ratings and inactive flag. ","description":"Get a FIDE player by FIDE id: name, title, federation, birth year, standard, rapid and blitz ratings and inactive flag. Use for \"What is the FIDE rating of player 1503014\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_id":{"description":"FIDE player id (a number), for example 1503014.","minimum":1,"title":"Player Id","type":"integer"}},"required":["player_id"],"title":"get_fide_playerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_fide_players":{"post":{"operationId":"search_fide_players","summary":"Search FIDE players by name: FIDE id, name, title, federation and standard, rapid and blitz ratings. Use for \"Find the F","description":"Search FIDE players by name: FIDE id, name, title, federation and standard, rapid and blitz ratings. Use for \"Find the FIDE player Carlsen\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Name to search for, for example 'Carlsen'.","maxLength":100,"title":"Q","type":"string"}},"required":["q"],"title":"search_fide_playersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_puzzle":{"post":{"operationId":"get_puzzle","summary":"Get a Lichess puzzle by id: rating, play count, themes, start position (FEN), last move and solution moves, plus the sou","description":"Get a Lichess puzzle by id: rating, play count, themes, start position (FEN), last move and solution moves, plus the source game id and players. Use for \"Show Lichess puzzle 20yfk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"puzzle_id":{"description":"Puzzle id, for example '20yfk'.","maxLength":12,"title":"Puzzle Id","type":"string"}},"required":["puzzle_id"],"title":"get_puzzleArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_live_streamers":{"post":{"operationId":"list_live_streamers","summary":"List Lichess users who are streaming right now: name, title, platform (Twitch or YouTube), stream status and language. U","description":"List Lichess users who are streaming right now: name, title, platform (Twitch or YouTube), stream status and language. Use for \"Which chess streamers are live on Lichess right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_live_streamersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/autocomplete_usernames":{"post":{"operationId":"autocomplete_usernames","summary":"Find Lichess usernames that start with the typed text (for example to fix a spelling), returning id, name, title and onl","description":"Find Lichess usernames that start with the typed text (for example to fix a spelling), returning id, name, title and online flag. Use for \"Which Lichess usernames start with 'thibau'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"description":"The beginning of a username, for example 'thibau'.","maxLength":30,"title":"Term","type":"string"},"object":{"anyOf":[{"const":true,"type":"boolean"},{"type":"null"}],"default":true,"description":"Always true here, so that user objects are returned instead of bare names; leave the default.","title":"Object"},"team":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only search inside this team (team id from its URL).","title":"Team"}},"required":["term"],"title":"autocomplete_usernamesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_crosstable":{"post":{"operationId":"get_crosstable","summary":"Get the total number of games and the current score between two Lichess users. Use for \"What is the head-to-head score b","description":"Get the total number of games and the current score between two Lichess users. Use for \"What is the head-to-head score between thibault and magnus on Lichess\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user1":{"description":"First Lichess username, for example 'thibault'.","maxLength":30,"title":"User1","type":"string"},"user2":{"description":"Second Lichess username, for example 'magnus'.","maxLength":30,"title":"User2","type":"string"}},"required":["user1","user2"],"title":"get_crosstableArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}