Lichess

Lichess Relations API

Access relations between users.

GitHub OpenAPI

Operations 5

GET /api/rel/following Get users followed by the logged in user #
POST /api/rel/follow/{username} Follow a player #
POST /api/rel/unfollow/{username} Unfollow a player #
POST /api/rel/block/{username} Block a player #
POST /api/rel/unblock/{username} Unblock a player #

Documentation

📖
Documentation
https://lichess.org/api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/openapi/lichess-relations-api-openapi.yml
⚙
AsyncAPI
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/asyncapi/lichess-asyncapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/json-schema/lichess-game-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/json-schema/lichess-user-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/json-ld/lichess-context.jsonld
🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/lichess/refs/heads/main/rules/lichess-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/lichess-relations-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lichess-relations-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  version: 2.0.144
  title: Lichess.org API reference Relations 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!'
servers:
- url: https://lichess.org
- url: https://lichess.dev
- url: http://localhost:{port}
  variables:
    port:
      default: '8080'
- url: http://l.org
tags:
- name: Relations
  description: Access relations between users.
paths:
  /api/rel/following:
    get:
      operationId: apiUserFollowing
      summary: Get users followed by the logged in user
      description: Users are streamed as ndjson.
      tags:
      - Relations
      security:
      - OAuth2:
        - follow:read
      responses:
        '200':
          description: The list of users followed by a user.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                default: '''*'''
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/UserExtended'
              examples:
                default:
                  $ref: '#/components/examples/relations-getMyFollowing.json'
  /api/rel/follow/{username}:
    post:
      operationId: followUser
      summary: Follow a player
      description: Follow a player, adding them to your list of Lichess friends.
      tags:
      - Relations
      security:
      - OAuth2:
        - follow:write
      parameters:
      - in: path
        name: username
        schema:
          type: string
          example: thibault
        required: true
      responses:
        '200':
          description: The player was successfully added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
              examples:
                default:
                  $ref: '#/components/examples/relations-followPlayer.json'
  /api/rel/unfollow/{username}:
    post:
      operationId: unfollowUser
      summary: Unfollow a player
      description: Unfollow a player, removing them from your list of Lichess friends.
      tags:
      - Relations
      security:
      - OAuth2:
        - follow:write
      parameters:
      - in: path
        name: username
        schema:
          type: string
          example: thibault
        required: true
      responses:
        '200':
          description: The player was successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
              examples:
                default:
                  $ref: '#/components/examples/relations-unfollowPlayer.json'
  /api/rel/block/{username}:
    post:
      operationId: blockUser
      summary: Block a player
      description: Block a player, adding them to your list of blocked Lichess users.
      tags:
      - Relations
      security:
      - OAuth2:
        - follow:write
      parameters:
      - in: path
        name: username
        schema:
          type: string
          example: thibault
        required: true
      responses:
        '200':
          description: The player was successfully added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
              examples:
                default:
                  $ref: '#/components/examples/relations-blockPlayer.json'
  /api/rel/unblock/{username}:
    post:
      operationId: unblockUser
      summary: Unblock a player
      description: Unblock a player, removing them from your list of blocked Lichess users.
      tags:
      - Relations
      security:
      - OAuth2:
        - follow:write
      parameters:
      - in: path
        name: username
        schema:
          type: string
          example: thibault
        required: true
      responses:
        '200':
          description: The player was successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ok'
              examples:
                default:
                  $ref: '#/components/examples/relations-unblockPlayer.json'
components:
  schemas:
    PlayTime:
      type: object
      properties:
        total:
          type: integer
        tv:
          type: integer
        human:
          type: integer
      required:
      - total
      - tv
    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
    PuzzleModePerf:
      type: object
      properties:
        runs:
          type: integer
        score:
          type: integer
      required:
      - runs
      - score
    Title:
      type: string
      enum:
      - GM
      - WGM
      - IM
      - WIM
      - FM
      - WFM
      - NM
      - CM
      - WCM
      - WNM
      - LM
      - BOT
      description: only appears if the user is a titled player or a bot user
    Flair:
      type: string
      description: See [available flair list and images](https://github.com/lichess-org/lila/tree/master/public/flair)
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        perfs:
          $ref: '#/components/schemas/Perfs'
        title:
          $ref: '#/components/schemas/Title'
        flair:
          $ref: '#/components/schemas/Flair'
        createdAt:
          type: integer
          format: int64
        disabled:
          type: boolean
          description: only appears if a user's account is closed
        tosViolation:
          type: boolean
          description: only appears if a user's account is marked for the violation of [Lichess TOS](https://lichess.org/terms-of-service)
        profile:
          $ref: '#/components/schemas/Profile'
        seenAt:
          type: integer
          format: int64
        playTime:
          $ref: '#/components/schemas/PlayTime'
        patron:
          $ref: '#/components/schemas/Patron'
        patronColor:
          $ref: '#/components/schemas/PatronColor'
        verified:
          type: boolean
      required:
      - id
      - username
    Perfs:
      type: object
      properties:
        chess960:
          $ref: '#/components/schemas/Perf'
        atomic:
          $ref: '#/components/schemas/Perf'
        racingKings:
          $ref: '#/components/schemas/Perf'
        ultraBullet:
          $ref: '#/components/schemas/Perf'
        blitz:
          $ref: '#/components/schemas/Perf'
        kingOfTheHill:
          $ref: '#/components/schemas/Perf'
        threeCheck:
          $ref: '#/components/schemas/Perf'
        antichess:
          $ref: '#/components/schemas/Perf'
        crazyhouse:
          $ref: '#/components/schemas/Perf'
        bullet:
          $ref: '#/components/schemas/Perf'
        correspondence:
          $ref: '#/components/schemas/Perf'
        horde:
          $ref: '#/components/schemas/Perf'
        puzzle:
          $ref: '#/components/schemas/Perf'
        classical:
          $ref: '#/components/schemas/Perf'
        rapid:
          $ref: '#/components/schemas/Perf'
        storm:
          $ref: '#/components/schemas/PuzzleModePerf'
        racer:
          $ref: '#/components/schemas/PuzzleModePerf'
        streak:
          $ref: '#/components/schemas/PuzzleModePerf'
    Perf:
      type: object
      properties:
        games:
          type: integer
        rating:
          type: integer
        rd:
          type: integer
          description: rating deviation
        prog:
          type: integer
        prov:
          type: boolean
          description: only appears if a user's perf rating are [provisional](https://lichess.org/faq#provisional)
        rank:
          type: integer
          description: global lichess ranking, only appears for recently active players
      required:
      - games
      - rating
      - rd
      - prog
    UserStreamer:
      type: object
      properties:
        twitch:
          type: object
          properties:
            channel:
              type: string
              format: uri
              example: https://www.twitch.tv/lichessdotorg
        youtube:
          type: object
          properties:
            channel:
              type: string
              format: uri
              example: https://www.youtube.com/c/LichessDotOrg
    Patron:
      type: boolean
      deprecated: true
      description: 'Use patronColor value instead to determine if player is a patron.

        '
    UserExtended:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          url:
            type: string
            format: uri
          playing:
            type: string
            format: uri
          count:
            $ref: '#/components/schemas/Count'
          streaming:
            type: boolean
          streamer:
            $ref: '#/components/schemas/UserStreamer'
          followable:
            type: boolean
            description: only appears if the request is [authenticated with OAuth2](#description/authentication)
          following:
            type: boolean
            description: only appears if the request is [authenticated with OAuth2](#description/authentication)
          blocking:
            type: boolean
            description: only appears if the request is [authenticated with OAuth2](#description/authentication)
          fideId:
            type: number
        required:
        - url
    Profile:
      type: object
      properties:
        flag:
          type: string
          example: EC
        location:
          type: string
        bio:
          type: string
          example: Free bugs!
        realName:
          type: string
          example: Thibault Duplessis
        fideRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        uscfRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        ecfRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        cfcRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        rcfRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        dsbRating:
          type: integer
          example: 1500
          description: only appears if a user has set them
        links:
          type: string
          example: 'github.com/ornicar

            mas.to/@thibault'
    Count:
      type: object
      properties:
        all:
          type: integer
        rated:
          type: integer
        ai:
          type: integer
        draw:
          type: integer
        drawH:
          type: integer
        loss:
          type: integer
        lossH:
          type: integer
        win:
          type: integer
        winH:
          type: integer
        bookmark:
          type: integer
        playing:
          type: integer
        import:
          type: integer
        me:
          type: integer
      required:
      - all
      - rated
      - draw
      - loss
      - win
      - bookmark
      - playing
      - import
      - me
    Ok:
      properties:
        ok:
          type: boolean
      required:
      - ok
  examples:
    relations-unfollowPlayer.json:
      value:
        ok: true
    relations-blockPlayer.json:
      value:
        ok: true
    relations-unblockPlayer.json:
      value:
        ok: true
    relations-followPlayer.json:
      value:
        ok: true
    relations-getMyFollowing.json:
      value:
        id: angel
        username: Angel
        perfs:
          bullet:
            games: 69
            rating: 2223
            rd: 47
            prog: -40
          blitz:
            games: 571
            rating: 2204
            rd: 76
            prog: 51
          rapid:
            games: 279
            rating: 2245
            rd: 46
            prog: -3
          classical:
            games: 36
            rating: 2366
            rd: 49
            prog: -43
          correspondence:
            games: 329
            rating: 2248
            rd: 114
            prog: -18
            prov: true
          chess960:
            games: 65
            rating: 2199
            rd: 45
            prog: 2
          kingOfTheHill:
            games: 2917
            rating: 2306
            rd: 64
            prog: -12
          threeCheck:
            games: 136
            rating: 2311
            rd: 45
            prog: -3
          antichess:
            games: 190
            rating: 2255
            rd: 79
            prog: 4
          atomic:
            games: 544
            rating: 2424
            rd: 100
            prog: 42
          horde:
            games: 50
            rating: 2345
            rd: 55
            prog: 52
          crazyhouse:
            games: 1717
            rating: 2286
            rd: 111
            prog: 5
            prov: true
          puzzle:
            games: 485
            rating: 2338
            rd: 58
            prog: -6
        title: CM
        flair: people.person-in-motorized-wheelchair-facing-right-medium-light-skin-tone
        patron: true
        patronColor: 1
        createdAt: 1774542084429
        seenAt: 1777308613557
        playTime:
          total: 15563
          tv: 0
        url: https://lichess.org/@/Angel
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'Read [the introduction for how to make authenticated requests](#description/authentication).

        '
      flows:
        authorizationCode:
          authorizationUrl: https://lichess.org/oauth
          tokenUrl: https://lichess.org/api/token
          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](#tag/bot/POST/api/bot/account/upgrade)
            web:mod: Use moderator tools (within the bounds of your permissions)