Public API

/api/public/v1 lists the same thing as JSON.

Every response has an apiVersion field and an X-API-Version header. A success carries the rows in data and a description in meta:

{
  "apiVersion": "1",
  "data": [
    { "opening": "Sicilian Defense", "games": 1832, "grandmasters": 214,
      "white_wins": 702, "black_wins": 641, "draws": 489, "white_score_pct": 51.7 }
  ],
  "meta": {
    "dataset": "openings",
    "fields": ["opening", "games", "grandmasters", "white_wins", "black_wins", "draws", "white_score_pct"],
    "count": 500,
    "generatedAt": "2026-09-25T12:00:00.000Z",
    "docs": "https://chessranger.com/developers"
  }
}

A failure carries error.code (unknown_dataset, read_failed or unavailable) and a readable error.message, with the matching HTTP status.

The version is in the path. Within v1, fields are only ever added — never renamed, removed or changed in type — so a client that ignores fields it does not know keeps working. A breaking change ships as a new version at a new path, and the old one keeps running alongside it for at least 90 days.

The older /api/datasets/[name] path still answers in its original shape and marks itself deprecated with a Link header pointing here.

A signed-in player can let an AI agent — Claude, or any client of the Model Context Protocol — read their own games, ratings and recurring mistakes, and ask it things like “what should I work on?”. Make a token in Settings → AI agents; it is shown once, reads only that player's data, cannot change anything, and can be revoked at any time.

claude mcp add --transport http chessranger https://chessranger.com/api/mcp   --header "Authorization: Bearer crt_…"

Any other client: the server is https://chessranger.com/api/mcp (Streamable HTTP, JSON answers), with the header Authorization: Bearer and the token. It speaks protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. The tools:

• get_summary — The player's overall picture on ChessRanger: games played (wins, draws, losses, as White and as Black), the first and latest game, the overall rating with its peak, and their five most-played openings with the score in each. Start here.
• get_ratings — Current ratings by time control — overall, bullet, blitz, rapid, classical, unlimited (no clock) and puzzle — each with games played and peak. Ratings come from games against the site's coach engine, so they are ChessRanger ratings, not FIDE, Chess.com or Lichess ones.
• get_rating_history — The player's rating after each rated game in one time control, oldest first, with the change each game made. Use it to describe a trend or a streak.
• get_recent_games — The player's latest games, newest first: date, their colour, opponent, result and how it ended, opening, number of moves, time control and the rating change. Filter by result or time control; ask for the PGN only when the moves are needed (it is long).
• get_mistake_profile — What keeps going wrong in the player's games: mistakes grouped by motif (hanging pieces, missed tactics, back-rank weakness…) and game phase, heaviest first — weighted by how much each cost and how recently it happened — each with a plain-English name, advice and a link to practise it on ChessRanger. Built from the games analysed in their browser.

Responses are cached at the edge for 60 minutes, which is also how often the data behind them is rebuilt, so polling faster than that returns the same bytes. Please cache on your side too. Heavy automated use may be rate-limited.

The openings and puzzle data come from games in the public Chess.com archive; puzzles are checked by a chess engine and ship without solutions. Questions, or need something that is not here? hello@chessranger.com. There is more about the site on the about page.