Interface Client

All Known Subinterfaces:
ClientAuth
public interface Client

Provides access to the Lichess API.

This interface provides access to the public API of Lichess (which doesn't need a Lichess account.) The ClientAuth interface provides access to the authenticated API of Lichess (which needs a Lichess account.)

Example of how to get a reference to a Client interface

Client client = Client.basic();

// Tada!

// And then use it...
var user = client.users().byId("lichess");

For accessing authenticated parts of the API, one needs a token with appropriate access rights / scopes. This library support PKCE Authorization Code flow (auth(Consumer, Consumer)), but one can also create a Personal Access Token manually.

Example of how to get a reference to a ClientAuth interface

String token = ... // Token with scope email:read
ClientAuth client = Client.auth(token);

// Tada!

// And then use it...
var email = client.account().emailAddress();

The responses from the API are modelled with One<T> and Many<T> "containers".
Their documentation covers different ways of accessing the contents of the containers.
The contents of the containers are typically data models from the chariot.model package.

  • Method Details

    • users

      UsersApi users()
      Access registered users on Lichess.

    • analysis

      AnalysisApi analysis()
      Access Lichess cloud evaluations database.

    • bot

      BotApi bot()
      Access Lichess online bots.
      For more bot operations, see ClientAuth.bot()

    • broadcasts

      BroadcastsApi broadcasts()
      Access Lichess broadcasts.

    • challenges

      ChallengesApi challenges()
      Open-ended challenges.
      For authenticated challenges, see ChallengesApiAuth

    • externalEngine

      ExternalEngineApi externalEngine()
      External engine.
      For engine management, see ExternalEngineApiAuth

    • fide

      FideApi fide()
      Download FIDE player info

    • games

      GamesApi games()
      Access games and TV channels, played on Lichess.

    • openingExplorer

      OpeningExplorerApi openingExplorer()
      Lookup positions from the Lichess opening explorer.

    • puzzles

      PuzzlesApi puzzles()
      Access Lichess puzzle history and dashboard.

    • simuls

      SimulsApi simuls()
      Access simuls played on Lichess.

    • studies

      StudiesApi studies()
      Access Lichess studies.

    • tablebase

      TablebaseApi tablebase()
      Lookup positions from the Lichess tablebase server.

    • teams

      TeamsApi teams()
      Access and manage Lichess teams and their members.

    • tournaments

      TournamentsApi tournaments()
      Access Arena and Swiss tournaments played on Lichess.

    • custom

      CustomApi custom()
      Use chariot for custom endpoints

    • store

      boolean store(Preferences prefs)
      Stores the client configuration into the provided preferences node.
      Parameters:
      prefs - The preferences node to store this client configuration to

    • basic

      static Client basic()
      Creates a default client

    • auth

      static ClientAuth auth(String token)
      Creates a default client using the provided token to use the authenticated parts of the API
      Parameters:
      token - A token to use for the authenticated parts of the API

    • basic

      static Client basic(Consumer<Builders.ConfigBuilder> params)
      Creates a customized client
      Parameters:
      params - A configuration parameters builder

    • withToken

      default ClientAuth withToken(String token)

      Use a pre-created Personal Access Token to use the authenticated API

      String token = ...
Client basic = Client.basic();
ClientAuth auth = basic.withToken(token);

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      token - pre-created Personal Access Token - @see Personal Access Token

    • withToken

      ClientAuth withToken(Supplier<char[]> token)

      Use a pre-created Personal Access Token to use the authenticated API

      Supplier<char[]> token = ...
Client basic = Client.basic();
ClientAuth auth = basic.withToken(token);

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      token - pre-created Personal Access Token - @see Personal Access Token

    • auth

      static ClientAuth auth(Consumer<Builders.ConfigBuilder> params, Supplier<char[]> token)
      Creates a customizable client using the provided configuration parameters builder.
      Parameters:
      params - A configuration parameters builder

    • auth

      static ClientAuth auth(Consumer<Builders.ConfigBuilder> params, String token)
      Creates a customizable client using the provided configuration parameters builder.
      Parameters:
      params - A configuration parameters builder

    • auth

      static ClientAuth auth(Supplier<char[]> token)
      Creates a default client using the provided token to use the authenticated parts of the API
      Parameters:
      token - A token to use for the authenticated parts of the API

    • withPkce

      One<ClientAuth> withPkce(Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      Client basic = Chariot.basic();

One<ClientAuth> authResult = basic.withPkce(
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof Entry(ClientAuth auth))) return;

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • auth

      static One<ClientAuth> auth(Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      One<ClientAuth> authResult = Client.auth(
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof Entry(ClientAuth auth))) return;

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • auth

      static One<ClientAuth> auth(Consumer<Builders.ConfigBuilder> config, Consumer<URI> uriHandler, Consumer<Client.PkceConfig> pkce)

      Use OAuth PKCE flow to make it possible for your user to grant access to your application.

      One<ClientAuth> authResult = Client.auth(
    conf -> conf.api("http://localhost:9663"),
    uri -> System.out.format("Visit %s to review and grant access%n", uri),
    pkce -> pkce.scope(Scope.challenge_read, Scope.challenge_write));

if (! (authResult instanceof Entry(ClientAuth auth))) return;

var challengeResult = auth.challenges().challenge(...);
      Parameters:
      config - Customized client configuration such as enabling logging and number of retries etc.
      uriHandler - The generated Lichess URI that your user can visit to review and approve granting access to your application
      pkce - Configuration of for instance which scopes if any that the resulting Access Token should include.

    • load

      static Client load(Preferences prefs)
      Creates a customized client from a preferences node
      See store(Preferences)
      Parameters:
      prefs -

      A configuration preferences node

        if (client instanceof ClientAuth auth) ...

    • load

      static ClientAuth load(Preferences prefs, String token)
      Creates an authenticated customized client from a preferences node with provided token
      Parameters:
      prefs - A configuration preferences node
      token - A token to use for the authenticated parts of the API

    • asAuth

      default Opt<ClientAuth> asAuth()
      Retrieves an Opt containing a ClientAuth if this is such a client, otherwise empty.

    • logging

      void logging(Consumer<Builders.LoggingBuilder> params)
      Configure logging levels