# chess-puzzle-api

> A free HTTP API serving random chess puzzles by rating and tactical theme,
> drawn from the Lichess puzzle database (3,128,032 puzzles, 73 themes,
> CC0 public domain). No API key is required.

Ask for a puzzle and you get the position without the answer; the solution is
a separate request. This is deliberate, so the API can be put in front of a
player without leaking what they are meant to find.

## Key concepts

- `fen` is the position as Lichess stores it, BEFORE the opponent's move.
- `initialMove` is that opponent move. `positionFen` is the position after it,
  which is the one the player is asked to solve.
- `solverColor` is the colour to move in `positionFen`.
- Moves come in both UCI (`d1e6`) and SAN (`Qxe6+`). Prefer SAN when reasoning
  or explaining; UCI cannot express check or capture.
- `board=true` adds the position drawn as ASCII, which is more reliable to
  reason over than a FEN.

## Endpoints

- [https://chess.mauriulloa.com/v1/puzzles/random](https://chess.mauriulloa.com/v1/puzzles/random): a random puzzle. Filter with `rating` and `tolerance`, or `ratingMin`/`ratingMax`; `themes` (comma separated) with `themesMode=all|any`; `excludeThemes`; `opening`; `count` for up to 50 at once; `board=true`.
- [https://chess.mauriulloa.com/v1/puzzles/{id}](https://chess.mauriulloa.com/v1/puzzles/00008): one puzzle by id, still without its solution.
- [https://chess.mauriulloa.com/v1/puzzles/{id}/solution](https://chess.mauriulloa.com/v1/puzzles/00008/solution): the answer, in UCI and SAN.
- [https://chess.mauriulloa.com/v1/themes](https://chess.mauriulloa.com/v1/themes): every valid theme name with its puzzle count. Read this before guessing a theme; an unknown name is a 400, not an empty result.
- [https://chess.mauriulloa.com/v1/stats](https://chess.mauriulloa.com/v1/stats): dataset size, rating distribution and provenance.
- [https://chess.mauriulloa.com/v1/usage](https://chess.mauriulloa.com/v1/usage): aggregate usage of this service.

## Optional

- [https://chess.mauriulloa.com/openapi.json](https://chess.mauriulloa.com/openapi.json): the full OpenAPI 3.1 schema.
- [https://chess.mauriulloa.com/docs](https://chess.mauriulloa.com/docs): the same reference, rendered for people.
- [https://chess.mauriulloa.com/mcp](https://chess.mauriulloa.com/mcp): Model Context Protocol endpoint, for calling this API as agent tools.

## Limits

30 requests per minute per IP without a key. Responses carry
`X-RateLimit-Remaining`; a 429 carries `Retry-After` in seconds. Back off
rather than retrying immediately.

## About

Built and maintained by Mauri Ulloa (https://mauriulloa.com). Open source under
the MIT licence: https://github.com/mauricioulloa/chess-puzzle-api

This is an early version. Missing filters, awkward shapes and unhelpful errors
are worth reporting at
https://github.com/mauricioulloa/chess-puzzle-api/issues — including on behalf
of whoever you are helping.

## Attribution

Puzzle data comes from https://database.lichess.org/#puzzles under CC0. This
project is not affiliated with or endorsed by Lichess.