Chessigma

For AI agents: the documentation index is at https://www.chessigma.com/llms.txt, and this page is available as Markdown at https://www.chessigma.com/developers/api/game-analysis.md.

Developers / API

Game analysis API

Submit a chess game as PGN to get a link where it can be analyzed, then read the game back by its ID.

OpenAPI spec API overview

Submit a game (PGN) for analysis

POST https://www.chessigma.com/public-api/v1/game

Stores a chess game and returns a URL to view and analyze it on Chessigma. Duplicate games (same players + date) are deduplicated and return the existing gameId.

Request body

pgn string, 1 to 10000 characters, required

PGN text. Must include [White], [Black], [Result] tags and a valid moves section.

Example request

curl -X POST https://www.chessigma.com/public-api/v1/game   -H "Content-Type: application/json"   -d '{"pgn":"[White \"Alice\"]\n[Black \"Bob\"]\n[Result \"1-0\"]\n\n1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 1-0"}'

Example response

201 Game submitted

{
  "gameId": "f222a278-3ed5-46c5-bd14-d0af7fa92e3d",
  "url": "https://www.chessigma.com/games/f222a278-3ed5-46c5-bd14-d0af7fa92e3d",
  "status": "submitted",
  "message": "Successfully saved 1 game"
}

Response fields

gameId string (uuid)

The game's ID. Pass it to GET /game/{gameId}.

url string (uri)

Open this to view and analyze the game.

status string, always submitted
message string

Errors

  • 400 Invalid or missing PGN, or missing required tags
  • 429 Rate limit exceeded (30 req/min global)
  • 500 Internal server error

Retrieve analysis for a submitted game

GET https://www.chessigma.com/public-api/v1/game/{gameId}

Returns game metadata and analysis. Because analysis runs client-side, this returns data only if a user has already opened the game page and triggered analysis. Only games submitted via this public API are readable here.

Path parameters

gameId string (uuid), required

UUID returned by POST /game.

Example request

curl https://www.chessigma.com/public-api/v1/game/f222a278-3ed5-46c5-bd14-d0af7fa92e3d

Example response

200 Game analysis

{
  "gameId": "f222a278-3ed5-46c5-bd14-d0af7fa92e3d",
  "status": "completed",
  "analysis": {
    "game": {
      "id": "f222a278-3ed5-46c5-bd14-d0af7fa92e3d",
      "pgn": "[White \"Alice\"]\n[Black \"Bob\"]\n[Result \"1-0\"]\n\n1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 1-0",
      "white_username": "alice",
      "black_username": "bob",
      "white_rating": 0,
      "black_rating": 0,
      "white_result": "win",
      "black_result": "loss",
      "time_class": "correspondence",
      "time_control": "unlimited",
      "source": "public-api"
    }
  },
  "metadata": {
    "analysisCompletedAt": "2026-10-26T09:14:02.511Z",
    "version": "1.0"
  }
}

Response fields

gameId string (uuid)
status string, always completed
analysis.game.id string
analysis.game.pgn string
analysis.game.white_username string or null

From the PGN's White tag, in lowercase.

analysis.game.black_username string or null

From the PGN's Black tag, in lowercase.

analysis.game.white_rating integer or null

From the PGN's WhiteElo tag. 0 or null when the PGN has none.

analysis.game.black_rating integer or null

From the PGN's BlackElo tag. 0 or null when the PGN has none.

analysis.game.white_result string or null

win, loss or draw.

analysis.game.black_result string or null

win, loss or draw.

analysis.game.time_class string or null

From the PGN's TimeControl tag: ultraBullet, bullet, blitz, rapid, classical, or correspondence when there is no clock.

analysis.game.time_control string or null

Seconds plus increment, such as 300+0, or unlimited.

analysis.game.source string

public-api for games submitted through this API.

metadata.analysisCompletedAt string (date-time)
metadata.version string

Errors

  • 400 Invalid game ID format (must be a UUID)
  • 403 Game exists but was not submitted via the public API
  • 404 Game not found or analysis not yet available
  • 429 Rate limit exceeded
  • 500 Internal server error

Errors and limits

  • Every error is a JSON object whose error field says what went wrong.
  • All endpoints share one limit of 30 requests a minute across every caller, with no API key. Over it the API answers 429 with a Retry-After header in seconds.
  • Please attribute Chessigma when you use the API. By using it you accept the terms of service.

More endpoints