LIlichess
Puzzles

Get multiple puzzles at once

Get a batch of random Lichess puzzles in JSON format.

If authenticated, only returns puzzles that the user has never seen before.

DO NOT use this endpoint to enumerate puzzles for mass download. Instead, download the full public puzzle database.

get/api/puzzle/batch/{angle}

Request

  • Base URL
    https://lichess.org
  • URL
    https://lichess.org/api/puzzle/batch/{angle}
  • Auth
    OAuth 2
    Authorization code: https://lichess.org/oauth
    Token URL: https://lichess.org/api/token scopes: puzzle:read

Path parameters

anglestring required
Example:mix

The theme or opening to filter puzzles with. Recommended: mix.

Available themes are listed in the lichess source code and the lichess training themes hyperlinks.

Query parameters

difficulty'easiest' | 'easier' | 'normal' | 'harder' | 'hardest'

The desired puzzle difficulty, relative to the authenticated user puzzle rating, or 1500 if anonymous.

nbinteger
Example:10

How many puzzles to fetch. Just set it to 1 if you only need one puzzle.

color'white' | 'black'

The color to play. Better left empty to automatically get 50% white. Currently only works when nb=1.

Response

The requested puzzles.

Changes

No recorded changes to this operation across all 16 revisions of this API.