Lichess Users API

openapi: 3.1.0
info:
  version: 2.0.144
  title: Lichess.org API reference Account Users API
  contact:
    name: Lichess.org API
    url: https://lichess.org/api
    email: contact@lichess.org
  x-logo:
    url: https://lichess1.org/assets/logo/lichess-pad12.svg
  license:
    name: AGPL-3.0-or-later
    url: https://www.gnu.org/licenses/agpl-3.0.txt
  description: '# Introduction

    Welcome to the reference for the Lichess API! Lichess is free/libre,

    open-source chess server powered by volunteers and donations.

    - Get help in the [Lichess Discord channel](https://discord.gg/lichess)

    - API demo app with OAuth2 login and gameplay: [source](https://github.com/lichess-org/api-demo) / [demo](https://lichess-org.github.io/api-demo/)

    - API UI app with OAuth2 login and endpoint forms: [source](https://github.com/lichess-org/api-ui) / [website](https://lichess.org/api/ui)

    - [Contribute to this documentation on Github](https://github.com/lichess-org/api)

    - Check out [Lichess widgets to embed in your website](https://lichess.org/developers)

    - [Download all Lichess rated games](https://database.lichess.org/)

    - [Download all Lichess puzzles with themes, ratings and votes](https://database.lichess.org/#puzzles)

    - [Download all evaluated positions](https://database.lichess.org/#evals)


    ## Endpoint

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


    ## Clients

    - [Python general API](https://github.com/lichess-org/berserk)

    - [MicroPython general API](https://github.com/mkomon/uberserk)

    - [Python general API - async](https://pypi.org/project/async-lichess-sdk)

    - [Python Lichess Bot](https://github.com/lichess-bot-devs/lichess-bot)

    - [Python Board API for Certabo](https://github.com/haklein/certabo-lichess)

    - [Java general API](https://github.com/tors42/chariot)

    - [JavaScript & TypeScript general API](https://github.com/devjiwonchoi/equine)

    - [LichessNET - C# API Wrapper](https://github.com/Rabergsel/LichessNET)

    - [.NET general API](https://github.com/Dblike/LichessSharp)


    ## 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](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429),

    you have exceded one of the rate limits.

    In most cases, waiting one minute before retrying will be sufficient, but some limits may require longer.

    Reduce your request frequency before retrying.


    ## Streaming with ND-JSON

    Some API endpoints stream their responses as [Newline Delimited JSON a.k.a. **nd-json**](https://github.com/ndjson/ndjson-spec), with one JSON object per line.


    Here''s a [JavaScript utility function](https://gist.github.com/ornicar/a097406810939cf7be1df8ea30e94f3e) to help reading NDJSON streamed responses.


    ## Authentication

    ### Which authentication method is right for me?

    [Read about the Lichess API authentication methods and code examples](https://github.com/lichess-org/api/blob/master/example/README.md)


    ### Personal Access Token

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

    - [Generate a personal access token](https://lichess.org/account/oauth/token)

    - `curl https://lichess.org/api/account -H "Authorization: Bearer {token}"`

    - [NodeJS example](https://github.com/lichess-org/api/tree/master/example/oauth-personal-token)


    ### 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](https://lichess.org/account/oauth/token).


    ### 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](#tag/OAuth) or

    the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636#section-4) for a precise protocol description.


    - [Demo app](https://lichess-org.github.io/api-demo/)

    - [Minimal client-side example](https://github.com/lichess-org/api/tree/master/example/oauth-app)

    - [Flask/Python example](https://github.com/lakinwecker/lichess-oauth-flask)

    - [Java example](https://github.com/tors42/lichess-oauth-pkce-app)

    - [NodeJS Passport strategy to login with Lichess OAuth2](https://www.npmjs.com/package/passport-lichess)


    #### Real life examples

    - [PyChess](https://github.com/gbtami/pychess-variants) ([source code](https://github.com/gbtami/pychess-variants))

    - [Lichess4545](https://www.lichess4545.com/) ([source code](https://github.com/cyanfish/heltour))

    - [English Chess Federation](https://ecf.octoknight.com/)

    - [Rotherham Online Chess](https://rotherhamonlinechess.azurewebsites.net/tournaments)


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

    '
servers:
- url: https://lichess.org
- url: https://lichess.dev
- url: http://localhost:{port}
  variables:
    port:
      default: '8080'
- url: http://l.org
tags:
- name: Users
  description: 'Access registered users on Lichess.

    <https://lichess.org/player>


    - Each user blog exposes an atom (RSS) feed, like <https://lichess.org/@/thibault/blog.atom>

    - User blogs mashup feed: https://lichess.org/blog/community.atom

    - User blogs mashup feed for a language: https://lichess.org/blog/community/fr.atom

    '
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: thibault,maia1,maia5
      - in: query
        name: withSignal
        required: false
        description: 'Also return the network signal of the player, when available.

          It ranges from 1 (poor connection, lag > 500ms) to 4 (great connection, lag < 150ms)

          Defaults to `false` to preserve server resources.

          '
        schema:
          type: boolean
        example: true
      - 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
      - in: query
        name: withGameMetas
        required: false
        description: 'Also return the id, time control and variant of the game being played, if any, for each player, in a `playing` field.

          Defaults to `false` to preserve server resources. Disables `withGameIds`.

          '
        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
                    flair:
                      $ref: '#/components/schemas/Flair'
                    title:
                      $ref: '#/components/schemas/Title'
                    online:
                      type: boolean
                    playing:
                      type: boolean
                    streaming:
                      type: boolean
                    patron:
                      $ref: '#/components/schemas/Patron'
                    patronColor:
                      $ref: '#/components/schemas/PatronColor'
                  required:
                  - id
                  - name
              examples:
                default:
                  $ref: '#/components/examples/users-getRealTimeUsersStatus.json'
  /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 <https://lichess.org/player>.

        '
      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'
              examples:
                default:
                  $ref: '#/components/examples/users-getAllTop10.json'
  /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 <https://lichess.org/player/top/100/bullet>.

        '
      parameters:
      - in: path
        name: nb
        description: How many users to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          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'
              examples:
                default:
                  $ref: '#/components/examples/users-getOneLeaderboard.json'
  /api/user/{username}:
    get:
      operationId: apiUser
      summary: Get user public data
      description: 'Read public data of a user.

        '
      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
      - in: query
        name: profile
        description: Include user profile data
        schema:
          type: boolean
          default: true
      - in: query
        name: rank
        description: Include global lichess ranking for each perf
        schema:
          type: boolean
          default: false
      - in: query
        name: fideId
        description: Include public FIDE ID if any
        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'
              examples:
                default:
                  $ref: '#/components/examples/users-getUserPublicData.json'
  /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'
              examples:
                default:
                  $ref: '#/components/examples/users-getRatingHistoryOfAUser.json'
  /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'
              examples:
                default:
                  $ref: '#/components/examples/users-getPerformanceStatisticsOfAUser.json'
  /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:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserActivity'
              examples:
                default:
                  $ref: '#/components/examples/users-getUserActivity.json'
  /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: thibault,maia1,maia5
      parameters:
      - in: query
        name: profile
        description: Include user profile data
        schema:
          type: boolean
          default: true
      - in: query
        name: rank
        description: Include global lichess ranking for each perf
        schema:
          type: boolean
          default: false
      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'
              examples:
                default:
                  $ref: '#/components/examples/users-getUsersById.json'
  /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:
                  type: object
                  allOf:
                  - $ref: '#/components/schemas/LightUser'
                  - type: object
                    properties:
                      stream:
                        type: object
                        properties:
                          service:
                            type: string
                            enum:
                            - twitch
                            - youtube
                          status:
                            type: string
                            description: The stream title
                          lang:
                            type: string
                      streamer:
                        type: object
                        properties:
                          name:
                            type: string
                          headline:
                            type: string
                          description:
                            type: string
                          twitch:
                            type: string
                            format: uri
                          youtube:
                            type: string
                            format: uri
                          image:
                            type: string
                            format: uri
              examples:
                default:
                  $ref: '#/components/examples/users-getLiveStreamers.json'
  /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'
              examples:
                default:
                  $ref: '#/components/examples/users-getCrosstable.json'
  /api/player/autocomplete:
    get:
      operationId: apiPlayerAutocomplete
      summary: Autocomplete usernames
      description: 'Provides autocompletion options for an incomplete username.

        '
      tags:
      - Users
      security:
      - {}
      - OAuth2: []
      parameters:
      - in: query
        name: term
        description: The beginning of a username
        schema:
          type: string
          minLength: 3
        required: true
      - in: query
        name: exists
        description: 'If `true`, only checks if the user exists.

          '
        schema:
          type: boolean
          default: false
      - 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: names
        description: '- `false` returns an array of usernames

          - `true` returns an array of usernames with preferred casing

          '
        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
      - in: query
        name: team
        description: 'Search within a team.

          Use team ID/slug.

          '
        schema:
          type: string
      - in: query
        name: tour
        description: 'Search within a arena tournament.

          Use tournament ID.

          '
        schema:
          type: string
      - in: query
        name: swiss
        description: 'Search within a Swiss tournament.

          '
        schema:
          type: string
      - in: query
        name: teacher
        description: 'Only search for players who also have a teacher role.

          '
        schema:
          type: boolean
          default: false
      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'
              examples:
                list of usernames:
                  $ref: '#/components/examples/users-autocompleteUsernames-list.json'
                array of user objects:
                  $ref: '#/components/examples/users-autocompleteUsernames-object.json'
  /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'
              examples:
                default:
                  $ref: '#/components/examples/users-addNoteForUser.json'
    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'
              examples:
                default:
                  $ref: '#/components/examples/users-getNotesForUser.json'
components:
  schemas:
    PuzzleModePerf:
      type: object
      properties:
        runs:
          type: integer
        score:
          type: integer
      required:
      - runs
      - score
    PatronColor:
      type: integer
      description: 'Players can choose a color for their Patron wings.

        See [here for the color mappings](https://github.com/lichess-org/lila/blob/master/ui/lib/css/abstract/_patron-colors.scss).


        The presence of this field indicates the player is an active Patron.

        '
      minimum: 1
      maximum: 10
    LightUserOnline:
      allOf:
      - $ref: '#/components/schemas/LightUser'
      - properties:
          online:
            type: boolean
    UserActivity:
      type: object
      properties:
        interval:
          type: object
          properties:
            start:
              type: integer
            end:
              type: integer
          required:
          - start
          - end
        games:
          type: object
          properties:
            chess960:
              $ref: '#/components/schemas/UserActivityScore'
            atomic:
              $ref: '#/components/schemas/UserActivityScore'
            racingKings:
              $ref: '#/components/schemas/UserActivityScore'
            ultraBullet:
              $ref: '#/components/schemas/UserActivityScore'
            blitz:
              $ref: '#/components/schemas/UserActivityScore'
            kingOfTheHill:
              $ref: '#/components/schemas/UserActivityScore'
            bullet:
              $ref: '#/components/schemas/UserActivityScore'
            correspondence:
              $ref: '#/components/schemas/UserActivityScore'
            horde:
              $ref: '#/components/schemas/UserActivityScore'
            puzzle:
              $ref: '#/components/schemas/UserActivityScore'
            classical:
              $ref: '#/components/schemas/UserActivityScore'
            rapid:
              $ref: '#/components/schemas/UserActivityScore'
        puzzles:
          type: object
          properties:
            score:
              $ref: '#/components/schemas/UserActivityScore'
        storm:
          $ref: '#/components/schemas/PuzzleModePerf'
        racer:
          $ref: '#/components/schemas/PuzzleModePerf'
        streak:
          $ref: '#/components/schemas/PuzzleModePerf'
        tournaments:
          type: object
          properties:
            nb:
              type: integer
            best:
              type: array
              items:
                type: object
                required:
                - tournament
                - nbGames
                - score
                - rank
                - rankPercent
                properties:
                  tournament:
                    type: object
                    required:
                    - id
                    - name
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                  nbGames:
                    type: integer
                  score:
                    type: integer
                  rank:
                    type: integer
                  rankPercent:
                    type: integer
        practice:
          type: array
          items:
            type: object
            required:
            - url
            - name
            - nbPositions
            properties:
              url:
                type: string
              name:
                type: string
              nbPositions:
                type: integer
        simuls:
          type: array
          items:
            type: string
        correspondenceMoves:
          type: object
          required:
          - nb
          - games
          properties:
            nb:
              type: integer
            games:
              type: array
              items:
                $ref: '#/components/schemas/UserActivityCorrespondenceGame'
        correspondenceEnds:
          type: object
          properties:
            correspondence:
              type: object
              properties:
                score:
                  $ref: '#/components/schemas/UserActivityScore'
                games:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserActivityCorrespondenceGame'
              required:
              - score
              - games
          required:
          - correspondence
        follows:
          type: object
          properties:
            in:
              $ref: '#/components/schemas/UserActivityFollowList'
            out:
              $ref: '#/components/schemas/UserActivityFollowList'
        studies:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
            required:
            - id
            - name
        teams:
          type: array
          items:
            type: object
            required:
            - url
            - name
            properties:
              url:
                type: string
                format: uri
              name:
                type: string
              flair:
                $ref: '#/components/schemas/Flair'
        posts:
          type: array
          items:
            type: object
            required:
            - topicUrl
            - topicName
            - posts
            properties:
              topicUrl:
                type: string
              topicName:
                type: string
              posts:
                type: array
                items:
                  type: object
                  required:
                  - url
                  - text
                  properties:
                    url:
                      type: string
                    text:
                      type: string
        patron:
          type: object
          required:
          - months
          p

# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/openapi/lichess-users-api-openapi.yml