boriskrusteff/lichess-php-sdk

PHP SDK for Lichess API

Maintainers

Details

github.com/boriskrusteff/lichess-php-sdk

Source

Issues

Installs: 2

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/boriskrusteff/lichess-php-sdk

v1.0.0 2025-12-26 20:52 UTC

Requires

  • php: >=8.1

MIT fb0d140e719b3c814facb4459c6249e8cee5eae9

This package is auto-updated.

Last update: 2025-12-26 20:56:21 UTC

README

Introduction

Welcome to the reference for the Lichess API! Lichess is free/libre, open-source chess server powered by volunteers and donations.

Endpoint

All requests go to https://lichess.org (unless otherwise specified).

Clients

Rate limiting

All requests are rate limited using various strategies, to ensure the API remains responsive for everyone. Only make one request at a time. If you receive an HTTP response with a 429 status, please wait a full minute before resuming API usage.

Streaming with ND-JSON

Some API endpoints stream their responses as Newline Delimited JSON a.k.a. nd-json, with one JSON object per line.

Here's a JavaScript utility function to help reading NDJSON streamed responses.

Authentication

Which authentication method is right for me?

Read about the Lichess API authentication methods and code examples

Personal Access Token

Personal API access tokens allow you to quickly interact with Lichess API without going through an OAuth flow.

Token Security

  • Keep your tokens secret. Do not share them in public repositories or public forums.
  • Your tokens can be used to make your account perform arbitrary actions (within the limits of the tokens' scope). You remain responsible for all activities on your account.
  • Do not hardcode tokens in your application's code. Use environment variables or a secure storage and ensure they are not shipped/exposed to users. Be especially careful that they are not included in frontend bundles or apps that are shipped to users.
  • If you suspect a token has been compromised, revoke it immediately.

To see your active tokens or revoke them, see your Personal API access tokens.

Authorization Code Flow with PKCE

The authorization code flow with PKCE allows your users to login with Lichess. Lichess supports unregistered and public clients (no client authentication, choose any unique client id). The only accepted code challenge method is S256. Access tokens are long-lived (expect one year), unless they are revoked. Refresh tokens are not supported.

See the documentation for the OAuth endpoints or the PKCE RFC for a precise protocol description.

Real life examples

Token format

Access tokens and authorization codes match ^[A-Za-z0-9_]+$. The length of tokens can be increased without notice. Make sure your application can handle at least 512 characters. By convention tokens have a recognizable prefix, but do not rely on this.

For more information, please visit https://lichess.org/api.

Installation & Usage

Requirements

PHP 8.1 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure OAuth2 access token for authorization: OAuth2
$config = Lichess\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Lichess\Api\AccountApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->account();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccountApi->account: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://lichess.org

Class Method HTTP request Description
AccountApi account GET /api/account/preferences Get my preferences
AccountApi accountEmail GET /api/account/email Get my email address
AccountApi accountKid GET /api/account/kid Get my kid mode status
AccountApi accountKidPost POST /api/account/kid Set my kid mode status
AccountApi accountMe GET /api/account Get my profile
AccountApi timeline GET /api/timeline Get my timeline
AnalysisApi apiCloudEval GET /api/cloud-eval Get cloud evaluation of a position.
BoardApi apiBoardSeek POST /api/board/seek Create a seek
BoardApi apiStreamEvent GET /api/stream/event Stream incoming events
BoardApi boardGameAbort POST /api/board/game/{gameId}/abort Abort a game
BoardApi boardGameBerserk POST /api/board/game/{gameId}/berserk Berserk a tournament game
BoardApi boardGameChatGet GET /api/board/game/{gameId}/chat Fetch the game chat
BoardApi boardGameChatPost POST /api/board/game/{gameId}/chat Write in the chat
BoardApi boardGameClaimDraw POST /api/board/game/{gameId}/claim-draw Claim draw of a game
BoardApi boardGameClaimVictory POST /api/board/game/{gameId}/claim-victory Claim victory of a game
BoardApi boardGameDraw POST /api/board/game/{gameId}/draw/{accept} Handle draw offers
BoardApi boardGameMove POST /api/board/game/{gameId}/move/{move} Make a Board move
BoardApi boardGameResign POST /api/board/game/{gameId}/resign Resign a game
BoardApi boardGameStream GET /api/board/game/stream/{gameId} Stream Board game state
BoardApi boardGameTakeback POST /api/board/game/{gameId}/takeback/{accept} Handle takeback offers
BotApi apiBotOnline GET /api/bot/online Get online bots
BotApi apiStreamEvent GET /api/stream/event Stream incoming events
BotApi botAccountUpgrade POST /api/bot/account/upgrade Upgrade to Bot account
BotApi botGameAbort POST /api/bot/game/{gameId}/abort Abort a game
BotApi botGameChat POST /api/bot/game/{gameId}/chat Write in the chat
BotApi botGameChatGet GET /api/bot/game/{gameId}/chat Fetch the game chat
BotApi botGameClaimDraw POST /api/bot/game/{gameId}/claim-draw Claim draw of a game
BotApi botGameClaimVictory POST /api/bot/game/{gameId}/claim-victory Claim victory of a game
BotApi botGameDraw POST /api/bot/game/{gameId}/draw/{accept} Handle draw offers
BotApi botGameMove POST /api/bot/game/{gameId}/move/{move} Make a Bot move
BotApi botGameResign POST /api/bot/game/{gameId}/resign Resign a game
BotApi botGameStream GET /api/bot/game/stream/{gameId} Stream Bot game state
BotApi botGameTakeback POST /api/bot/game/{gameId}/takeback/{accept} Handle takeback offers
BroadcastsApi broadcastAllRoundsPgn GET /api/broadcast/{broadcastTournamentId}.pgn Export all rounds as PGN
BroadcastsApi broadcastMyRoundsGet GET /api/broadcast/my-rounds Get your broadcast rounds
BroadcastsApi broadcastPlayerGet GET /broadcast/{broadcastTournamentId}/players/{playerId} Get a player of a broadcast
BroadcastsApi broadcastPlayersGet GET /broadcast/{broadcastTournamentId}/players Get players of a broadcast
BroadcastsApi broadcastPush POST /api/broadcast/round/{broadcastRoundId}/push Push PGN to a broadcast round
BroadcastsApi broadcastRoundCreate POST /broadcast/{broadcastTournamentId}/new Create a broadcast round
BroadcastsApi broadcastRoundGet GET /api/broadcast/{broadcastTournamentSlug}/{broadcastRoundSlug}/{broadcastRoundId} Get a broadcast round
BroadcastsApi broadcastRoundPgn GET /api/broadcast/round/{broadcastRoundId}.pgn Export one round as PGN
BroadcastsApi broadcastRoundReset POST /api/broadcast/round/{broadcastRoundId}/reset Reset a broadcast round
BroadcastsApi broadcastRoundUpdate POST /broadcast/round/{broadcastRoundId}/edit Update a broadcast round
BroadcastsApi broadcastStreamRoundPgn GET /api/stream/broadcast/round/{broadcastRoundId}.pgn Stream an ongoing broadcast round as PGN
BroadcastsApi broadcastTourCreate POST /broadcast/new Create a broadcast tournament
BroadcastsApi broadcastTourGet GET /api/broadcast/{broadcastTournamentId} Get a broadcast tournament
BroadcastsApi broadcastTourUpdate POST /broadcast/{broadcastTournamentId}/edit Update your broadcast tournament
BroadcastsApi broadcastsByUser GET /api/broadcast/by/{username} Get broadcasts created by a user
BroadcastsApi broadcastsOfficial GET /api/broadcast Get official broadcasts
BroadcastsApi broadcastsSearch GET /api/broadcast/search Search broadcasts
BroadcastsApi broadcastsTop GET /api/broadcast/top Get paginated top broadcast previews
BulkPairingsApi bulkPairingCreate POST /api/bulk-pairing Create a bulk pairing
BulkPairingsApi bulkPairingDelete DELETE /api/bulk-pairing/{id} Cancel a bulk pairing
BulkPairingsApi bulkPairingGet GET /api/bulk-pairing/{id} Show a bulk pairing
BulkPairingsApi bulkPairingIdGamesGet GET /api/bulk-pairing/{id}/games Export games of a bulk pairing
BulkPairingsApi bulkPairingList GET /api/bulk-pairing View your bulk pairings
BulkPairingsApi bulkPairingStartClocks POST /api/bulk-pairing/{id}/start-clocks Manually start clocks
ChallengesApi adminChallengeTokens POST /api/token/admin-challenge Admin challenge tokens
ChallengesApi challengeAccept POST /api/challenge/{challengeId}/accept Accept a challenge
ChallengesApi challengeAi POST /api/challenge/ai Challenge the AI
ChallengesApi challengeCancel POST /api/challenge/{challengeId}/cancel Cancel a challenge
ChallengesApi challengeCreate POST /api/challenge/{username} Create a challenge
ChallengesApi challengeDecline POST /api/challenge/{challengeId}/decline Decline a challenge
ChallengesApi challengeList GET /api/challenge List your challenges
ChallengesApi challengeOpen POST /api/challenge/open Open-ended challenge
ChallengesApi challengeShow GET /api/challenge/{challengeId}/show Show one challenge
ChallengesApi challengeStartClocks POST /api/challenge/{gameId}/start-clocks Start clocks of a game
ChallengesApi roundAddTime POST /api/round/{gameId}/add-time/{seconds} Add time to the opponent clock
ExternalEngineApi apiExternalEngineAcquire POST /api/external-engine/work Acquire analysis request
ExternalEngineApi apiExternalEngineAnalyse POST /api/external-engine/{id}/analyse Analyse with external engine
ExternalEngineApi apiExternalEngineCreate POST /api/external-engine Create external engine
ExternalEngineApi apiExternalEngineDelete DELETE /api/external-engine/{id} Delete external engine
ExternalEngineApi apiExternalEngineGet GET /api/external-engine/{id} Get external engine
ExternalEngineApi apiExternalEngineList GET /api/external-engine List external engines
ExternalEngineApi apiExternalEnginePut PUT /api/external-engine/{id} Update external engine
ExternalEngineApi apiExternalEngineSubmit POST /api/external-engine/work/{id} Answer analysis request
FIDEApi fidePlayerGet GET /api/fide/player/{playerId} Get a FIDE player
FIDEApi fidePlayerSearch GET /api/fide/player Search FIDE players
GamesApi apiAccountPlaying GET /api/account/playing Get my ongoing games
GamesApi apiExportBookmarks GET /api/games/export/bookmarks Export your bookmarked games
GamesApi apiGamesUser GET /api/games/user/{username} Export games of a user
GamesApi apiImportedGamesUser GET /api/games/export/imports Export your imported games
GamesApi apiUserCurrentGame GET /api/user/{username}/current-game Export ongoing game of a user
GamesApi gameImport POST /api/import Import one game
GamesApi gamePgn GET /game/export/{gameId} Export one game
GamesApi gamesByIds POST /api/stream/games/{streamId} Stream games by IDs
GamesApi gamesByIdsAdd POST /api/stream/games/{streamId}/add Add game IDs to stream
GamesApi gamesByUsers POST /api/stream/games-by-users Stream games of users
GamesApi gamesExportIds POST /api/games/export/_ids Export games by IDs
GamesApi streamGame GET /api/stream/game/{id} Stream moves of a game
MessagingApi inboxUsername POST /inbox/{username} Send a private message
OAuthApi apiToken POST /api/token Obtain access token
OAuthApi apiTokenDelete DELETE /api/token Revoke access token
OAuthApi oauth GET /oauth Request authorization code
OAuthApi tokenTest POST /api/token/test Test multiple OAuth tokens
OpeningExplorerApi openingExplorerLichess GET /lichess Lichess games
OpeningExplorerApi openingExplorerMaster GET /masters Masters database
OpeningExplorerApi openingExplorerMasterGame GET /master/pgn/{gameId} OTB master game
OpeningExplorerApi openingExplorerPlayer GET /player Player games
PuzzlesApi apiPuzzleActivity GET /api/puzzle/activity Get your puzzle activity
PuzzlesApi apiPuzzleBatchSelect GET /api/puzzle/batch/{angle} Get multiple puzzles at once
PuzzlesApi apiPuzzleBatchSolve POST /api/puzzle/batch/{angle} Solve multiple puzzles at once
PuzzlesApi apiPuzzleDaily GET /api/puzzle/daily Get the daily puzzle
PuzzlesApi apiPuzzleDashboard GET /api/puzzle/dashboard/{days} Get your puzzle dashboard
PuzzlesApi apiPuzzleId GET /api/puzzle/{id} Get a puzzle by its ID
PuzzlesApi apiPuzzleNext GET /api/puzzle/next Get a new puzzle
PuzzlesApi apiPuzzleReplay GET /api/puzzle/replay/{days}/{theme} Get puzzles to replay
PuzzlesApi apiStormDashboard GET /api/storm/dashboard/{username} Get the storm dashboard of a player
PuzzlesApi racerGet GET /api/racer/{id} Get puzzle race results
PuzzlesApi racerPost POST /api/racer Create and join a puzzle race
RelationsApi apiUserFollowing GET /api/rel/following Get users followed by the logged in user
RelationsApi blockUser POST /api/rel/block/{username} Block a player
RelationsApi followUser POST /api/rel/follow/{username} Follow a player
RelationsApi unblockUser POST /api/rel/unblock/{username} Unblock a player
RelationsApi unfollowUser POST /api/rel/unfollow/{username} Unfollow a player
SimulsApi apiSimul GET /api/simul Get current simuls
StudiesApi apiStudyChapterTags POST /api/study/{studyId}/{chapterId}/tags Update PGN tags of a study chapter
StudiesApi apiStudyImportPGN POST /api/study/{studyId}/import-pgn Import PGN into a study
StudiesApi apiStudyStudyIdChapterIdDelete DELETE /api/study/{studyId}/{chapterId} Delete a study chapter
StudiesApi studyAllChaptersHead HEAD /api/study/{studyId}.pgn Study metadata
StudiesApi studyAllChaptersPgn GET /api/study/{studyId}.pgn Export all chapters
StudiesApi studyChapterPgn GET /api/study/{studyId}/{chapterId}.pgn Export one study chapter
StudiesApi studyExportAllPgn GET /study/by/{username}/export.pgn Export all studies of a user
StudiesApi studyListMetadata GET /api/study/by/{username} List studies of a user
TVApi tvChannelFeed GET /api/tv/{channel}/feed Stream current TV game of a TV channel
TVApi tvChannelGames GET /api/tv/{channel} Get best ongoing games of a TV channel
TVApi tvChannels GET /api/tv/channels Get current TV games
TVApi tvFeed GET /api/tv/feed Stream current TV game
TablebaseApi antichessAtomic GET /antichess Tablebase lookup for Antichess
TablebaseApi tablebaseAtomic GET /atomic Tablebase lookup for Atomic chess
TablebaseApi tablebaseStandard GET /standard Tablebase lookup
TeamsApi apiTeamArena GET /api/team/{teamId}/arena Get team Arena tournaments
TeamsApi apiTeamSwiss GET /api/team/{teamId}/swiss Get team swiss tournaments
TeamsApi teamAll GET /api/team/all Get popular teams
TeamsApi teamIdJoin POST /team/{teamId}/join Join a team
TeamsApi teamIdKickUserId POST /api/team/{teamId}/kick/{userId} Kick a user from your team
TeamsApi teamIdPmAll POST /team/{teamId}/pm-all Message all members
TeamsApi teamIdQuit POST /team/{teamId}/quit Leave a team
TeamsApi teamIdUsers GET /api/team/{teamId}/users Get members of a team
TeamsApi teamOfUsername GET /api/team/of/{username} Teams of a player
TeamsApi teamRequestAccept POST /api/team/{teamId}/request/{userId}/accept Accept join request
TeamsApi teamRequestDecline POST /api/team/{teamId}/request/{userId}/decline Decline join request
TeamsApi teamRequests GET /api/team/{teamId}/requests Get join requests
TeamsApi teamSearch GET /api/team/search Search teams
TeamsApi teamShow GET /api/team/{teamId} Get a single team
TournamentsArenaApi apiTeamArena GET /api/team/{teamId}/arena Get team Arena tournaments
TournamentsArenaApi apiTournament GET /api/tournament Get current tournaments
TournamentsArenaApi apiTournamentJoin POST /api/tournament/{id}/join Join an Arena tournament
TournamentsArenaApi apiTournamentPost POST /api/tournament Create a new Arena tournament
TournamentsArenaApi apiTournamentTeamBattlePost POST /api/tournament/team-battle/{id} Update a team battle
TournamentsArenaApi apiTournamentTerminate POST /api/tournament/{id}/terminate Terminate an Arena tournament
TournamentsArenaApi apiTournamentUpdate POST /api/tournament/{id} Update an Arena tournament
TournamentsArenaApi apiTournamentWithdraw POST /api/tournament/{id}/withdraw Pause or leave an Arena tournament
TournamentsArenaApi apiUserNameTournamentCreated GET /api/user/{username}/tournament/created Get tournaments created by a user
TournamentsArenaApi apiUserNameTournamentPlayed GET /api/user/{username}/tournament/played Get tournaments played by a user
TournamentsArenaApi gamesByTournament GET /api/tournament/{id}/games Export games of an Arena tournament
TournamentsArenaApi resultsByTournament GET /api/tournament/{id}/results Get results of an Arena tournament
TournamentsArenaApi teamsByTournament GET /api/tournament/{id}/teams Get team standing of a team battle
TournamentsArenaApi tournament GET /api/tournament/{id} Get info about an Arena tournament
TournamentsSwissApi apiSwissJoin POST /api/swiss/{id}/join Join a Swiss tournament
TournamentsSwissApi apiSwissNew POST /api/swiss/new/{teamId} Create a new Swiss tournament
TournamentsSwissApi apiSwissScheduleNextRound POST /api/swiss/{id}/schedule-next-round Manually schedule the next round
TournamentsSwissApi apiSwissTerminate POST /api/swiss/{id}/terminate Terminate a Swiss tournament
TournamentsSwissApi apiSwissUpdate POST /api/swiss/{id}/edit Update a Swiss tournament
TournamentsSwissApi apiSwissWithdraw POST /api/swiss/{id}/withdraw Pause or leave a swiss tournament
TournamentsSwissApi apiTeamSwiss GET /api/team/{teamId}/swiss Get team swiss tournaments
TournamentsSwissApi gamesBySwiss GET /api/swiss/{id}/games Export games of a Swiss tournament
TournamentsSwissApi resultsBySwiss GET /api/swiss/{id}/results Get results of a swiss tournament
TournamentsSwissApi swiss GET /api/swiss/{id} Get info about a Swiss tournament
TournamentsSwissApi swissTrf GET /swiss/{id}.trf Export TRF of a Swiss tournament
UsersApi apiCrosstable GET /api/crosstable/{user1}/{user2} Get crosstable
UsersApi apiPlayerAutocomplete GET /api/player/autocomplete Autocomplete usernames
UsersApi apiUser GET /api/user/{username} Get user public data
UsersApi apiUserActivity GET /api/user/{username}/activity Get user activity
UsersApi apiUserPerf GET /api/user/{username}/perf/{perf} Get performance statistics of a user
UsersApi apiUserRatingHistory GET /api/user/{username}/rating-history Get rating history of a user
UsersApi apiUsers POST /api/users Get users by ID
UsersApi apiUsersStatus GET /api/users/status Get real-time users status
UsersApi player GET /api/player Get all top 10
UsersApi playerTopNbPerfType GET /api/player/top/{nb}/{perfType} Get one leaderboard
UsersApi readNote GET /api/user/{username}/note Get notes for a user
UsersApi streamerLive GET /api/streamer/live Get live streamers
UsersApi writeNote POST /api/user/{username}/note Add a note for a user

Models

Authorization

Authentication schemes defined for the API:

OAuth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://lichess.org/oauth
  • Scopes:
    • preference:read: Read your preferences
    • preference:write: Write your preferences
    • email:read: Read your email address
    • engine:read: Read your external engines
    • engine:write: Create, update, delete your external engines
    • challenge:read: Read incoming challenges
    • challenge:write: Create, accept, decline challenges
    • challenge:bulk: Create, delete, query bulk pairings
    • study:read: Read private studies and broadcasts
    • study:write: Create, update, delete studies and broadcasts
    • tournament:write: Create tournaments
    • racer:write: Create and join puzzle races
    • puzzle:read: Read puzzle activity
    • puzzle:write: Write puzzle activity
    • team:read: Read private team information
    • team:write: Join, leave teams
    • team:lead: Manage teams (kick members, send PMs)
    • follow:read: Read followed players
    • follow:write: Follow and unfollow other players
    • msg:write: Send private messages to other players
    • board:play: Play with the Board API
    • bot:play: Play with the Bot API. Only for Bot accounts
    • web:mod: Use moderator tools (within the bounds of your permissions)

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

contact@lichess.org

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 2.0.110
    • Generator version: 7.18.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen