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