ChessOverAPI

Play chess over an API!

This API can make chess sessions, then you can send moves, get legal moves, render the board, and even let a bot do the move, it's made with python FastAPI, the python-chess library and stockfish for the bot, it uses uvicorn as web server and cairosvg for SVG rendering.

---

Demo

There is a demo instance online on https://api-for-chess.tuxworld.nl/, click here to play with UI, or here to view the docs.

---

How to use?

You can open the play page at /play, there you can use the UI to play chess against the bot, or you can send GET and POST requests the to the server, you can view the enpoints here.

---

Run

python -m pip install -e '.[dev]'
uvicorn app.main:app --reload

---

Stockfish

This API uses Stockfish for the bot to play chess, if Stockfish is configured correctly, the bot will use Stockfish for the bot. If Stockfish is not available, the API falls back to a random move. To configure Stockfish, you need to rename example.config.toml to config.toml and edit the path setting in this file. You can also set an evnvironment variable instead:

export STOCKFISH_PATH=/path/to/stockfish

---

Endpoints

POST /sessions Creates a new chess game session.

Response:

{
  "session_id": "abc123",
  "fen": "starting position"
}

GET /sessions/{session_id}/board

Gets the current board state.

Response:

{
  "fen": "current position",
  "game_over": false,
  "result": null
}

POST /sessions/{session_id}/move

Makes a move using UCI format (like e2e4).

Request:

{
  "move": "e2e4"
}

Response:

{
  "success": true,
  "move": "e2e4",
  "fen": "new position"
}

POST /sessions/{session_id}/bot-move

Lets the computer make a move.

Response:

{
  "success": true,
  "move": "g8f6",
  "fen": "new position"
}

GET /sessions/{session_id}/board.svg

Gets an image of the chess board.

Example:

GET /sessions/{session_id}/board.svg?selected=e4&highlights=e4,e5

GET /sessions/{session_id}/legal-moves

Gets all legal moves from a square.

Example:

GET /sessions/{session_id}/legal-moves?from=e2

Response:

{
  "moves": {
    "e4": "e2e4",
    "e3": "e2e3"
  }
}