openapi: '3.0.2'
info:
title: Chess
version: '1.0'
servers:
- url: https://api.chess.com/
paths:
/pub/player/{username}:
get:
summary: Get additional details about a player in a game.
description: Get additional details about a player in a game.
operationId: getPlayerProfile
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/titled/{title}:
get:
summary: List of titled-player usernames.
description: List of titled-player usernames.
operationId: getTitledPlayers
parameters:
- name: title
in: path
required: true
schema:
$ref: '#/components/schemas/Title'
example: GM
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
description: array of usernames for players with this title
items:
type: string
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/stats:
get:
summary: Get player stats.
description: Get ratings, win/loss, and other stats about a player's game play, tactics, lessons and Puzzle Rush score.
operationId: getPlayerStats
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerStats'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/is-online:
get:
summary: Get player online status.
description: Tells if a user has been online in the last five minutes.
operationId: getPlayerOnlineStatus
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
online:
type: boolean
required:
- online
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/games:
get:
summary: Current Daily Chess
description: Get list of Daily Chess games that a player is currently playing
operationId: getDailyChessGames
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
games:
type: array
description: Array of Daily Chess games that a player is currently playing
items:
$ref: '#/components/schemas/DailyGame'
required:
- games
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/games/to-move:
get:
summary: To-Move Daily Chess
description: Get list of Daily Chess games where it is the player's turn to move
operationId: getDailyChessGamesToMove
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
games:
type: array
description: Array of Daily Chess games where it is the player's turn to move
items:
$ref: '#/components/schemas/ToMoveGame'
required:
- games
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/games/archives:
get:
summary: List of Monthly Archives
description: Get list of monthly archives available for this player
operationId: getChessGamesArchives
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
archives:
type: array
description: List of URLs for monthly archives in ascending chronological order
items:
type: string
format: uri
required:
- archives
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/games/{year}/{month}:
get:
summary: Complete Monthly Archives
description: Get list of Live and Daily Chess games that a player has finished
operationId: getChessGamesForMonth
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
- name: year
in: path
description: Four digit year of the game-end
required: true
schema:
type: string
example: 2021
- name: month
in: path
description: Two-digit month of the game-end
required: true
schema:
type: string
example: 03
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
games:
type: array
description: List of Live and Daily Chess games that a player has finished
items:
$ref: '#/components/schemas/CompletedGame'
required:
- games
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/pub/player/{username}/games/{year}/{month}/pgn:
get:
summary: Multi-Game PGN Download
description: Get standard multi-game format PGN containing all games for a month
operationId: getChessGamesForMonthPGN
parameters:
- name: username
in: path
required: true
schema:
type: string
example: rgnever
- name: year
in: path
description: Four digit year of the game-end
required: true
schema:
type: string
example: 2021
- name: month
in: path
description: Two-digit month of the game-end
required: true
schema:
type: string
example: 03
responses:
'200':
description: OK
content:
application/x-chess-pgn:
schema:
type: string
format: pgn
description: This response follows the PGN standard, and is not JSON-encoded.
headers:
Content-Disposition:
schema:
type: string
description: Indicates client should download, not display, the result
example: attachment; filename="ChessCom_username_{{year}}{{month}}.pgn"
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
responses:
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Request exceeded rate limit
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Player:
type: string
enum: [white, black]
Title:
type: string
enum: [GM, WGM, IM, WIM, FM, WFM, NM, WNM, CM, WCM]
Profile:
type: object
properties:
"@id":
type: string
format: uri
url:
type: string
format: uri
username:
type: string
player_id:
type: integer
title:
$ref: '#/components/schemas/Title'
status:
type: string
enum:
- closed
- closed:fair_play_violations
- basic
- premium
- mod
- staff
name:
type: string
avatar:
type: string
format: uri
location:
type: string
country:
type: string
format: uri
joined:
type: integer
format: timestamp
last_online:
type: integer
format: timestamp
followers:
type: integer
is_streamer:
type: boolean
twitch_url:
type: string
format: uri
fide:
type: integer
required:
- "@id"
- url
- username
- player_id
- status
- country
- joined
- last_online
- followers
- is_streamer
PlayerStats:
type: object
properties:
chess_daily:
$ref: '#/components/schemas/ChessStats'
chess_rapid:
$ref: '#/components/schemas/ChessStats'
chess_blitz:
$ref: '#/components/schemas/ChessStats'
chess_bullet:
$ref: '#/components/schemas/ChessStats'
chess960_daily:
$ref: '#/components/schemas/ChessStats'
chess960_rapid:
$ref: '#/components/schemas/ChessStats'
chess960_blitz:
$ref: '#/components/schemas/ChessStats'
chess960_bullet:
$ref: '#/components/schemas/ChessStats'
tactics:
$ref: '#/components/schemas/TacticsStats'
lessons:
$ref: '#/components/schemas/LessonsStats'
puzzle_rush:
$ref: '#/components/schemas/PuzzleRushStats'
ChessStats:
type: object
properties:
last:
type: object
properties:
rating:
type: integer
minimum: 0
description: Most-recent rating
date:
type: integer
format: timestamp
description: Timestamp of the last rated game finished
rd:
type: integer
minimum: 0
description: Glicko "RD" value used to calculate ratings changes
required:
- rating
- date
- rd
best:
type: object
description: Best rating achieved by a win
properties:
rating:
type: integer
minimum: 0
description: Highest rating achieved
date:
type: integer
format: timestamp
description: Timestamp of the best-win game
game:
type: string
format: uri
description: URL of the best-win game
required:
- rating
- date
- game
record:
type: object
description: Summary of all games played
properties:
win:
type: integer
minimum: 0
description: Number of games won
loss:
type: integer
minimum: 0
description: Number of games lost
draw:
type: integer
minimum: 0
description: Number of games drawn
time_per_move:
type: integer
minimum: 0
description: Number of seconds per average move
timeout_percent:
type: number
format: float
minimum: 0
description: Timeout percentage in the last 90 days
required:
- win
- loss
- draw
tournament:
type: object
description: Summary of tournaments participated in
properties:
count:
type: integer
minimum: 0
description: Number of tournaments joined
withdraw:
type: integer
minimum: 0
description: Number of tournaments withdrawn from
points:
type: integer
minimum: 0
description: Total number of points earned in tournaments
highest_finish:
type: integer
minimum: 0
description: Best tournament place
required:
- count
- withdraw
- points
- highest_finish
required:
- last
- record
Rating:
type: object
properties:
rating:
type: integer
date:
type: integer
format: timestamp
required:
- rating
- date
TacticsStats:
type: object
properties:
higest:
$ref: '#/components/schemas/Rating'
lowest:
$ref: '#/components/schemas/Rating'
LessonsStats:
type: object
properties:
higest:
$ref: '#/components/schemas/Rating'
lowest:
$ref: '#/components/schemas/Rating'
Score:
type: object
properties:
score:
type: integer
date:
type: integer
format: timestamp
required:
- score
- date
PuzzleRushStats:
type: object
properties:
higest:
$ref: '#/components/schemas/Score'
lowest:
$ref: '#/components/schemas/Score'
DailyGame:
type: object
properties:
white:
type: string
format: uri
description: URL of the white player's profile
black:
type: string
format: uri
description: URL of the black player's profile
url:
type: string
format: uri
description: URL of this game
fen:
type: string
description: Current FEN
pgn:
type: string
description: Current PGN
turn:
description: Player to move
$ref: '#/components/schemas/Player'
move_by:
type: integer
format: timestamp
description: Timestamp of when the next move must be made
draw_offer:
description: Player who has made a draw offer (optional)
$ref: '#/components/schemas/Player'
last_activity:
type: integer
format: timestamp
description: Timestamp of the last activity on the game
start_time:
type: integer
format: timestamp
description: Timestamp of the game start (Daily Chess only)
time_control:
type: string
description: PGN-compliant time control
time_class:
type: string
enum: [daily, rapid, blitz, bullet]
description: Time-per-move grouping, used for ratings
rules:
type: string
enum: [chess, chess960, bughouse, kingofthehill, threecheck, crazyhouse]
description: Game variant information (e.g., "chess960")
tournament:
type: string
format: uri
description: URL pointing to tournament (if available)
match:
type: string
format: uri
description: URL pointing to team match (if available)
required:
- white
- black
- url
- fen
- pgn
- turn
- last_activity
- time_control
- time_class
- rules
ToMoveGame:
type: object
properties:
url:
type: string
format: uri
description: URL of this game
move_by:
type: integer
format: timestamp
description: Timestamp of when the next move must be made
draw_offer:
description: Player who has made a draw offer (optional)
type: boolean
last_activity:
type: integer
format: timestamp
description: Timestamp of the last activity on the game
required:
- url
- move_by
- last_activity
PlayerResult:
type: object
properties:
username:
type: string
rating:
type: integer
description: The player's rating at the start of the game
minimum: 0
result:
type: string
enum: [win, checkmated, agreed, repetition, timeout, resigned, stalemate, lose, insufficient, 50move, abandoned, kingofthehill, threecheck, timevsinsufficient, bughousepartnerlose]
description: |
Player result:
* `win` - Win
* `checkmated` - Checkmated
* `agreed` - Draw agreed
* `repetition` - Draw by repetition
* `timeout` - Timeout
* `resigned` - Resigned
* `stalemate` - Stalemate
* `lose` - Lose
* `insufficient` - Insufficient material
* `50` - Draw by 50-move rule
* `abandoned` - abandoned
* `kingofthehill` - Opponent king reached the hill
* `threecheck` - Checked for the 3rd time
* `timevsinsufficient` - Draw by timeout vs insufficient material
* `bughousepartnerlose` - Bughouse partner lost
"@id":
type: string
description: URL of this player's profile
required:
- username
- rating
- result
- "@id"
CompletedGame:
type: object
properties:
white:
description: Details of the white-piece player
$ref: '#/components/schemas/PlayerResult'
black:
description: Details of the white-piece player
$ref: '#/components/schemas/PlayerResult'
url:
type: string
format: uri
description: URL of this game
fen:
type: string
description: Current FEN
pgn:
type: string
description: Current PGN
start_time:
type: integer
format: timestamp
description: Timestamp of the game start (Daily Chess only)
end_time:
type: integer
format: timestamp
description: Timestamp of the game end
rated: type: boolean
description: Indicates if the game was rated
time_control:
type: string
description: PGN-compliant time control
time_class: type: string
enum: [daily, rapid, blitz, bullet]
description: Time-per-move grouping, used for ratings
rules:
type: string
enum: [chess, chess960, bughouse, kingofthehill, threecheck, crazyhouse]
description: Game variant information (e.g., "chess960")
eco:
type: string
description: URL pointing to ECO opening (if available)
tournament:
type: string
format: uri
description: URL pointing to tournament (if available)
match:
type: string
format: uri
description: URL pointing to team match (if available)
required:
- white
- black
- url
- fen
- pgn
- end_time
- rated
- time_control
- time_class
- rules
Error:
type: object
properties:
code:
type: integer
message:
type: string
required:
- code
- message