canonical: https://jentic.com/apis/chess.com/chess

# Chess.com Published-Data API

Jentic publishes the only available OpenAPI specification for Chess.com Published-Data API, keeping it validated and agent-ready. The read-only service returns public Chess.com data: player profiles and statistics, monthly game archives, clubs, team matches, country pages, daily puzzles, streamers, and leaderboards. Responses are JSON and need no authentication, so an agent can read any public username or club straight away.

## For AI agents

Lets an AI agent look up public Chess.com players, their game archives, clubs, tournaments, and daily puzzles without any credentials.

## Scope

Does not create accounts, play moves, or write any data: use it for reading public Chess.com profiles, games, and clubs only.

## Capabilities

- Retrieve a player's profile, ratings, and win and loss statistics
- Pull monthly game archives in PGN and JSON for any public username
- Check whether a player is online and which games await their move
- Browse clubs, their members, and team match results
- Read country pages, titled-player lists, and global leaderboards
- Fetch the daily puzzle or a random puzzle for study tools

## Use cases

### Game analysis and coaching tools

Chess coaching and analysis apps need a player's recent games to review mistakes and track progress. The Chess.com API returns monthly archives in PGN and JSON for any public account, so a tool can pull a student's games and feed them to an engine or lesson plan.

Example prompt: Fetch last month's rated games for a given username and return them as PGN for engine analysis

### Player scouting and rating dashboards

Scouting and leaderboard dashboards track ratings and activity across many accounts. The API exposes per-player statistics, online status, and the global leaderboards, letting a dashboard refresh standings and compare players without scraping.

Example prompt: Read a player's blitz, rapid, and bullet ratings and compare them against the current leaderboard

### Agent-driven chess study assistant

An AI study assistant can answer questions about a player and set up practice. Through Jentic, an agent resolves a request like reviewing a user's week into the right read operations, pulling profile, recent games, and the daily puzzle in sequence.

Example prompt: Given a username, gather the player's profile, this month's games, and the daily puzzle for a study session

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/player/{username}` | Get a player's profile |
| GET | `/player/{username}/stats` | Get a player's rating statistics |
| GET | `/player/{username}/games` | Get a player's current daily games |
| GET | `/player/{username}/games/{year}/{month}` | Get a monthly game archive |
| GET | `/leaderboards` | Get the global leaderboards |
| GET | `/puzzle` | Get the daily puzzle |

## Key resources

- **Players** — Profiles, statistics, online status, and per-player game listings
- **Games** — Current daily games and monthly archives in PGN and JSON
- **Clubs and matches** — Club profiles, members, and team match results
- **Tournaments** — Tournament details, rounds, and groups
- **Puzzles and leaderboards** — Daily and random puzzles plus global leaderboards

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 56 / 100
  - AI-Readiness & Agent Experience: 43 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 62 / 100
- **View full report:** https://jentic.com/apis/chess.com/chess/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Chess.com needs no key, so the only real work is handling its per-endpoint URL shapes and JSON responses. With Jentic One you install once, import the read operations from the API Directory, and point an agent at them.
- **Permission scoping:** Every operation is read-only, and because resources like username and club id are path parameters you can scope an agent to specific reads such as player statistics or leaderboards.
- **Credential handling:** There is no credential to handle: the service is public, so nothing is stored and no secret ever reaches the agent's prompt or logs.
- **Discovery method:** Agents find the right Chess.com read through Jentic's intent search, matching a request like getting a chess player's rating to the exact operation.

## Related APIs

- **Lichess** — Open-source chess platform with a broader read and write API
- **TheSportsDB** — Crowd-sourced sports data across many leagues and teams
- **AllSportsAPI** — Live scores and fixtures across multiple sports

## FAQ

### Do I need an API key to use the Chess.com API?

No. The published-data service is read-only and public, so there is no key to request and nothing to store. Jentic One sends each request straight through to Chess.com.

### Can I limit what my agent is allowed to do with the Chess.com API?

Yes. Every operation is a read, and you choose which read operations to import into your Jentic One instance, so an agent can be allowed to fetch player statistics while being blocked from everything else.

### What data does the Chess.com API return?

Public player profiles and statistics, monthly game archives, clubs and team matches, country pages, tournaments, daily puzzles, streamers, and leaderboards, all as JSON.

### Is Chess.com game history available in PGN?

Yes. Monthly archives return each game in both PGN and JSON, so analysis tools can replay moves directly.

### Why is there no official OpenAPI spec for Chess.com?

Chess.com documents its published-data service in prose rather than a machine-readable spec. Jentic generated this OpenAPI description from that documentation and keeps it validated so agents can call it reliably.