openapi: 3.1.0
info:
title: Chess.com Published Data API
description: |
Public, read-only REST API exposing Chess.com data: player profiles and stats, monthly game
archives (JSON and PGN), clubs and members, daily and live team matches, Swiss and round-robin
tournaments, titled-player lists, country rosters, the daily puzzle, the streamer list, and
live leaderboards.
The API is unauthenticated; rate limiting applies to parallel requests (429 Too Many Requests).
Responses use JSON-LD with ETag, Last-Modified, gzip, and JSONP support. Most endpoints refresh
at most every 12-24 hours. Clients are encouraged to send a recognizable User-Agent including a
contact email or URL.
version: '2026-05-25'
contact:
name: Chess.com Support
url: https://support.chess.com
x-logo:
url: https://www.chess.com/favicon.ico
servers:
- url: https://api.chess.com/pub
description: Chess.com Published Data API
tags:
- name: Players
description: Profiles, stats, online state, archives, clubs, matches, tournaments
- name: Games
description: Daily, live, and archived games (JSON and PGN)
- name: Clubs
description: Club profiles, members, and team matches
- name: Tournaments
description: Tournament details, rounds, and groups
- name: Matches
description: Daily and live team match details
- name: Countries
description: Country profiles, players, and clubs
- name: Puzzles
description: Daily and random puzzles
- name: Streamers
description: Chess.com streamers
- name: Leaderboards
description: Live leaderboards across time controls and variants
- name: Titled Players
description: Lists of titled players by FIDE title
paths:
/player/{username}:
get:
summary: Get Player Profile
operationId: getPlayerProfile
tags: [Players]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Player profile
content:
application/json:
schema:
$ref: '#/components/schemas/Player'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/player/{username}/stats:
get:
summary: Get Player Stats
operationId: getPlayerStats
tags: [Players]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Ratings and statistics across time controls and modes
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerStats'
'404':
$ref: '#/components/responses/NotFound'
/player/{username}/is-online:
get:
summary: Get Player Online Status
operationId: getPlayerOnline
tags: [Players]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Online state
content:
application/json:
schema:
type: object
properties:
online:
type: boolean
/player/{username}/games:
get:
summary: Get Player Current Daily Games
operationId: getPlayerCurrentGames
tags: [Players, Games]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: In-progress daily chess games
content:
application/json:
schema:
type: object
properties:
games:
type: array
items:
$ref: '#/components/schemas/Game'
/player/{username}/games/to-move:
get:
summary: Get Player Games To Move
operationId: getPlayerGamesToMove
tags: [Players, Games]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Daily games waiting on the player to move
content:
application/json:
schema:
type: object
/player/{username}/games/archives:
get:
summary: List Player Game Archives
operationId: listPlayerArchives
tags: [Players, Games]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: URLs of available monthly archives
content:
application/json:
schema:
type: object
properties:
archives:
type: array
items:
type: string
format: uri
/player/{username}/games/{year}/{month}:
get:
summary: Get Player Monthly Archive
operationId: getPlayerMonthlyArchive
tags: [Players, Games]
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Year'
- $ref: '#/components/parameters/Month'
responses:
'200':
description: All games completed in the given month
content:
application/json:
schema:
type: object
properties:
games:
type: array
items:
$ref: '#/components/schemas/Game'
/player/{username}/games/{year}/{month}/pgn:
get:
summary: Get Player Monthly Archive PGN
operationId: getPlayerMonthlyArchivePgn
tags: [Players, Games]
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Year'
- $ref: '#/components/parameters/Month'
responses:
'200':
description: All games in the given month as a multi-game PGN stream
content:
application/x-chess-pgn:
schema:
type: string
/player/{username}/clubs:
get:
summary: Get Player Club Memberships
operationId: getPlayerClubs
tags: [Players, Clubs]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Clubs the player belongs to
content:
application/json:
schema:
type: object
/player/{username}/matches:
get:
summary: Get Player Team Matches
operationId: getPlayerMatches
tags: [Players, Matches]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Team match participation
content:
application/json:
schema:
type: object
/player/{username}/tournaments:
get:
summary: Get Player Tournaments
operationId: getPlayerTournaments
tags: [Players, Tournaments]
parameters:
- $ref: '#/components/parameters/Username'
responses:
'200':
description: Tournaments the player has registered for
content:
application/json:
schema:
type: object
/titled/{title-abbrev}:
get:
summary: List Titled Players
operationId: listTitledPlayers
tags: [Titled Players]
parameters:
- name: title-abbrev
in: path
required: true
schema:
type: string
enum: [GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM]
responses:
'200':
description: List of titled players
content:
application/json:
schema:
type: object
properties:
players:
type: array
items:
type: string
/club/{url-ID}:
get:
summary: Get Club Profile
operationId: getClub
tags: [Clubs]
parameters:
- $ref: '#/components/parameters/ClubUrlId'
responses:
'200':
description: Club profile
content:
application/json:
schema:
$ref: '#/components/schemas/Club'
/club/{url-ID}/members:
get:
summary: Get Club Members
operationId: getClubMembers
tags: [Clubs]
parameters:
- $ref: '#/components/parameters/ClubUrlId'
responses:
'200':
description: Club members grouped by activity level
content:
application/json:
schema:
type: object
properties:
weekly:
type: array
items:
$ref: '#/components/schemas/ClubMember'
monthly:
type: array
items:
$ref: '#/components/schemas/ClubMember'
all_time:
type: array
items:
$ref: '#/components/schemas/ClubMember'
/club/{url-ID}/matches:
get:
summary: Get Club Matches
operationId: getClubMatches
tags: [Clubs, Matches]
parameters:
- $ref: '#/components/parameters/ClubUrlId'
responses:
'200':
description: Team matches for the club
content:
application/json:
schema:
type: object
/tournament/{url-ID}:
get:
summary: Get Tournament
operationId: getTournament
tags: [Tournaments]
parameters:
- $ref: '#/components/parameters/TournamentUrlId'
responses:
'200':
description: Tournament summary
content:
application/json:
schema:
type: object
/tournament/{url-ID}/{round}:
get:
summary: Get Tournament Round
operationId: getTournamentRound
tags: [Tournaments]
parameters:
- $ref: '#/components/parameters/TournamentUrlId'
- name: round
in: path
required: true
schema:
type: integer
responses:
'200':
description: Round details
content:
application/json:
schema:
type: object
/tournament/{url-ID}/{round}/{group}:
get:
summary: Get Tournament Round Group
operationId: getTournamentRoundGroup
tags: [Tournaments]
parameters:
- $ref: '#/components/parameters/TournamentUrlId'
- name: round
in: path
required: true
schema:
type: integer
- name: group
in: path
required: true
schema:
type: integer
responses:
'200':
description: Group standings within a round
content:
application/json:
schema:
type: object
/match/{ID}:
get:
summary: Get Daily Team Match
operationId: getDailyMatch
tags: [Matches]
parameters:
- $ref: '#/components/parameters/MatchId'
responses:
'200':
description: Daily team match details
content:
application/json:
schema:
type: object
/match/{ID}/{board}:
get:
summary: Get Daily Team Match Board
operationId: getDailyMatchBoard
tags: [Matches]
parameters:
- $ref: '#/components/parameters/MatchId'
- $ref: '#/components/parameters/Board'
responses:
'200':
description: Daily team match board
content:
application/json:
schema:
type: object
/match/live/{ID}:
get:
summary: Get Live Team Match
operationId: getLiveMatch
tags: [Matches]
parameters:
- $ref: '#/components/parameters/MatchId'
responses:
'200':
description: Live team match details
content:
application/json:
schema:
type: object
/match/live/{ID}/{board}:
get:
summary: Get Live Team Match Board
operationId: getLiveMatchBoard
tags: [Matches]
parameters:
- $ref: '#/components/parameters/MatchId'
- $ref: '#/components/parameters/Board'
responses:
'200':
description: Live team match board
content:
application/json:
schema:
type: object
/country/{iso}:
get:
summary: Get Country Profile
operationId: getCountry
tags: [Countries]
parameters:
- $ref: '#/components/parameters/Iso'
responses:
'200':
description: Country profile
content:
application/json:
schema:
type: object
properties:
'@id':
type: string
name:
type: string
code:
type: string
/country/{iso}/players:
get:
summary: List Players By Country
operationId: listCountryPlayers
tags: [Countries, Players]
parameters:
- $ref: '#/components/parameters/Iso'
responses:
'200':
description: Players for the given country
content:
application/json:
schema:
type: object
properties:
players:
type: array
items:
type: string
/country/{iso}/clubs:
get:
summary: List Clubs By Country
operationId: listCountryClubs
tags: [Countries, Clubs]
parameters:
- $ref: '#/components/parameters/Iso'
responses:
'200':
description: Clubs for the given country
content:
application/json:
schema:
type: object
properties:
clubs:
type: array
items:
type: string
/puzzle:
get:
summary: Get Daily Puzzle
operationId: getDailyPuzzle
tags: [Puzzles]
responses:
'200':
description: The daily puzzle
content:
application/json:
schema:
$ref: '#/components/schemas/Puzzle'
/puzzle/random:
get:
summary: Get Random Daily Puzzle
operationId: getRandomPuzzle
tags: [Puzzles]
responses:
'200':
description: A randomly selected past daily puzzle
content:
application/json:
schema:
$ref: '#/components/schemas/Puzzle'
/streamers:
get:
summary: List Chess.com Streamers
operationId: listStreamers
tags: [Streamers]
responses:
'200':
description: Chess.com streamers and their channel URLs
content:
application/json:
schema:
type: object
properties:
streamers:
type: array
items:
$ref: '#/components/schemas/Streamer'
/leaderboards:
get:
summary: Get Leaderboards
operationId: getLeaderboards
tags: [Leaderboards]
responses:
'200':
description: Top 50 players across all formats
content:
application/json:
schema:
type: object
components:
parameters:
Username:
name: username
in: path
required: true
description: All-lowercase Chess.com username
schema:
type: string
Year:
name: year
in: path
required: true
description: Four-digit year
schema:
type: string
pattern: '^[0-9]{4}$'
Month:
name: month
in: path
required: true
description: Two-digit month
schema:
type: string
pattern: '^(0[1-9]|1[0-2])$'
ClubUrlId:
name: url-ID
in: path
required: true
description: Club URL-ID slug from chess.com/club/{url-ID}
schema:
type: string
TournamentUrlId:
name: url-ID
in: path
required: true
description: Tournament URL-ID slug from chess.com/tournament/{url-ID}
schema:
type: string
MatchId:
name: ID
in: path
required: true
description: Numeric team-match ID
schema:
type: integer
Board:
name: board
in: path
required: true
description: Board number within the team match
schema:
type: integer
Iso:
name: iso
in: path
required: true
description: ISO 3166-1 alpha-2 country code (e.g. US, RU, IN)
schema:
type: string
minLength: 2
maxLength: 2
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Too Many Requests — parallel-request throttling
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Player:
type: object
properties:
'@id':
type: string
format: uri
url:
type: string
format: uri
username:
type: string
player_id:
type: integer
title:
type: string
status:
type: string
name:
type: string
avatar:
type: string
format: uri
location:
type: string
country:
type: string
format: uri
joined:
type: integer
description: Unix timestamp
last_online:
type: integer
followers:
type: integer
is_streamer:
type: boolean
twitch_url:
type: string
format: uri
fide:
type: integer
PlayerStats:
type: object
properties:
chess_daily:
$ref: '#/components/schemas/RatingProfile'
chess_rapid:
$ref: '#/components/schemas/RatingProfile'
chess_blitz:
$ref: '#/components/schemas/RatingProfile'
chess_bullet:
$ref: '#/components/schemas/RatingProfile'
tactics:
type: object
puzzle_rush:
type: object
fide:
type: integer
RatingProfile:
type: object
properties:
last:
type: object
properties:
rating:
type: integer
date:
type: integer
rd:
type: integer
best:
type: object
record:
type: object
properties:
win:
type: integer
loss:
type: integer
draw:
type: integer
Game:
type: object
properties:
url:
type: string
format: uri
pgn:
type: string
time_control:
type: string
end_time:
type: integer
rated:
type: boolean
fen:
type: string
time_class:
type: string
enum: [daily, rapid, blitz, bullet]
rules:
type: string
enum: [chess, chess960, bughouse, kingofthehill, threecheck, crazyhouse]
white:
$ref: '#/components/schemas/GamePlayer'
black:
$ref: '#/components/schemas/GamePlayer'
GamePlayer:
type: object
properties:
rating:
type: integer
result:
type: string
enum: [win, checkmated, agreed, repetition, timeout, resigned, stalemate, lose, insufficient,
'50move', abandoned, kingofthehill, threecheck, bughousepartnerlose]
'@id':
type: string
format: uri
username:
type: string
Club:
type: object
properties:
'@id':
type: string
name:
type: string
club_id:
type: integer
country:
type: string
average_daily_rating:
type: integer
members_count:
type: integer
created:
type: integer
last_activity:
type: integer
admin:
type: array
items:
type: string
visibility:
type: string
join_request:
type: string
description:
type: string
ClubMember:
type: object
properties:
username:
type: string
joined:
type: integer
Puzzle:
type: object
properties:
title:
type: string
url:
type: string
format: uri
publish_time:
type: integer
fen:
type: string
pgn:
type: string
image:
type: string
format: uri
Streamer:
type: object
properties:
username:
type: string
avatar:
type: string
format: uri
twitch_url:
type: string
format: uri
url:
type: string
format: uri
is_live:
type: boolean
Error:
type: object
properties:
code:
type: integer
message:
type: string