Lichess.org API reference (2.0.0)

Download OpenAPI specification:Download

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).

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

OAuth2

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.

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.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://lichess.org/oauth
Token URL: https://lichess.org/api/token
Scopes:
  • preference:read -

    Read your preferences

  • preference:write -

    Write your preferences

  • email:read -

    Read your email address

  • 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

  • puzzle:read -

    Read puzzle activity

  • team:read -

    Read private team information

  • team:write -

    Join, leave, and manage teams

  • 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)

Account

Read and write account information and preferences. https://lichess.org/account/preferences/game-display

Get my profile

Public information about the logged in user.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "id": "georges",
  • "username": "Georges",
  • "online": true,
  • "perfs": {
    },
  • "createdAt": 1290415680000,
  • "disabled": false,
  • "tosViolation": false,
  • "profile": {
    },
  • "seenAt": 1522636452014,
  • "patron": true,
  • "verified": true,
  • "playTime": {
    },
  • "title": "NM",
  • "completionRate": 97,
  • "count": {
    },
  • "streaming": false,
  • "followable": true,
  • "following": false,
  • "blocking": false,
  • "followsYou": false
}

Get my email address

Read the email address of the logged in user.

Authorizations:
OAuth2 (
  • email:read
)

Responses

Response samples

Content type
application/json
{
  • "email": "abathur@mail.org"
}

Get my preferences

Authorizations:
OAuth2 (
  • preference:read
)

Responses

Response samples

Content type
application/json
{
  • "prefs": {
    },
  • "language": "en-GB"
}

Get my kid mode status

Read the kid mode status of the logged in user.

Authorizations:
OAuth2 (
  • preference:read
)

Responses

Response samples

Content type
application/json
{
  • "kid": false
}

Set my kid mode status

Set the kid mode status of the logged in user.

Authorizations:
OAuth2 (
  • preference:write
)
query Parameters
v
required
boolean
Example: v=true

Kid mode status

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Users

Access registered users on Lichess. https://lichess.org/player

Get real-time users status

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.

query Parameters
ids
required
string
Example: ids=aliquantus,chess-network,lovlas

User IDs separated by commas. Up to 100 IDs.

withGameIds
boolean
Example: withGameIds=true

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.

Responses