Lichess Analysis API

openapi: 3.2.0
info:
  version: 2.0.144
  title: Lichess.org API reference Analysis 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: Analysis
  description: Access Lichess cloud evaluations database.
paths:
  /api/cloud-eval:
    get:
      operationId: apiCloudEval
      summary: Get cloud evaluation of a position
      description: 'Get the cached evaluation of a position, if available.

        Opening positions have more chances of being available. There are about 320 million positions in the database.

        Up to 5 variations may be available. Variants are supported.

        Use this endpoint to fetch a few positions here and there.

        If you want to download a lot of positions, get the full list from our exported database.'
      tags:
      - Analysis
      security: []
      parameters:
      - in: query
        name: fen
        required: true
        description: X-FEN of the position
        schema:
          type: string
        example: r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3
      - in: query
        name: multiPv
        description: Number of variations
        schema:
          type: integer
          default: 1
      - in: query
        name: variant
        description: Variant
        schema:
          $ref: '#/components/schemas/VariantKey'
      responses:
        '200':
          description: The evaluation of the position.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                default: '''*'''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudEval'
        '404':
          description: The position was not found in the cloud evaluation database.
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: No cloud evaluation available for that position
components:
  schemas:
    CloudEval:
      type: object
      required:
      - depth
      - fen
      - knodes
      - pvs
      properties:
        depth:
          type: integer
        fen:
          type: string
        knodes:
          type: integer
        pvs:
          type: array
          items:
            oneOf:
            - type: object
              title: Non-mate variation
              required:
              - cp
              - moves
              properties:
                cp:
                  type: integer
                  description: Evaluation in centi-pawns, from White's point of view
                moves:
                  type: string
                  description: 'Variation in UCI notation (King to rook for Chess960-compatible

                    castling notation)

                    '
            - type: object
              title: Mate variation
              required:
              - mate
              - moves
              properties:
                mate:
                  type: integer
                  description: Evaluation in moves to mate, from White's point of view
                moves:
                  type: string
                  description: 'Variation in UCI notation (King to rook for Chess960-compatible

                    castling notation)

                    '
      example:
        fen: r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R
        knodes: 106325
        depth: 29
        pvs:
        - moves: d1e2 d8e7 a2a4 a7a6 b5c4 d7d6 d2d3 g8f6 c1e3 c6a5
          cp: 41
        - moves: c2c3 a7a6 b5a4 g8f6 d2d3 b7b5 a4b3 h7h6 a2a4 c8b7
          cp: 39
        - moves: d2d3 d8f6 c2c3 a7a6 b5a4 f8c5 d3d4 c5a7 c1e3 g8e7
          cp: 37
    VariantKey:
      type: string
      enum:
      - standard
      - chess960
      - crazyhouse
      - antichess
      - atomic
      - horde
      - kingOfTheHill
      - racingKings
      - threeCheck
      - fromPosition
      example: standard
      default: standard
  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)