Get a random chess puzzle. Optionally filter by a target rating (a random puzzle within 100 of it is returned) and/or themes (matching at least one). With no parameters, returns a truly random puzzle from the dataset with no filtering.
Parameters
rating
integer
Optional
a target Glicko-2 rating; a random puzzle whose rating is within 100 of this value is returned. When omitted, rating is not filtered.
themes
array
of string
Optional
restrict the result to puzzles matching at least one of these themes (e.g. "fork", "endgame"). When omitted, themes are not filtered.
Output
Encoding
application/jsonErrors
PuzzleNotFound
No puzzle matches the given rating and/or theme filters. Try It
Requests are sent directly from your browser. Some servers may block requests due to CORS.
View raw schema
{
"type": "query",
"errors": [
{
"name": "PuzzleNotFound",
"description": "No puzzle matches the given rating and/or theme filters."
}
],
"output": {
"schema": {
"ref": "org.lichess.puzzle.defs#puzzleView",
"type": "ref"
},
"encoding": "application/json"
},
"parameters": {
"type": "params",
"properties": {
"rating": {
"type": "integer",
"minimum": 0,
"description": "a target Glicko-2 rating; a random puzzle whose rating is within 100 of this value is returned. When omitted, rating is not filtered."
},
"themes": {
"type": "array",
"items": {
"type": "string"
},
"description": "restrict the result to puzzles matching at least one of these themes (e.g. \"fork\", \"endgame\"). When omitted, themes are not filtered."
}
}
},
"description": "Get a random chess puzzle. Optionally filter by a target rating (a random puzzle within 100 of it is returned) and/or themes (matching at least one). With no parameters, returns a truly random puzzle from the dataset with no filtering."
}