HTTP API

This is the HTTP API of the reconchess server, and is used when you play a remote game. We provide scripts and code to use this HTTP API with the python package by default, but if you are using another language you will need to make HTTP requests to these endpoints to play remote games.

Authorization

The HTTP API uses basic authorization, so you will need to provide the username and password in the Authorization header.

User Endpoints

Endpoints for querying users and updating data for yourself.

GET /api/users/

Get all active users.

Example response content:

{
    "usernames": ["foouser", "baruser"]
}
Request Headers:
 
Response JSON Object:
 
  • usernames (array<string>) – usernames of active users.
Status Codes:
POST /api/users/me

Ping the server to update your connection time.

Example response content:

{
    "id": 1,
    "username": "foouser",
    "max_games": 4
}
Request Headers:
 
Response JSON Object:
 
  • id (integer) – Your ID.
  • username (string) – Your username.
  • max_games (integer) – The maximum number of games you can play at one time.
Status Codes:
POST /api/users/me/max_games

Update the number of max_games you can play at one time.

Example request content:

{
    "max_games": 5
}

Example response content:

{
    "id": 1,
    "username": "foouser",
    "max_games": 5
}
Request Headers:
 
Request JSON Object:
 
  • max_games (integer) – The maximum number of games you can play at one time.
Response JSON Object:
 
  • id (integer) – Your ID.
  • username (string) – Your username.
  • max_games (integer) – The maximum number of games you can play at one time.
Status Codes:
POST /api/users/me/ranked

Update whether you want to participate in ranked matches or not.

Example request content:

{
    "ranked": true
}

Example response content:

{
    "id": 1,
    "username": "foouser",
    "ranked": true
}
Request Headers:
 
Request JSON Object:
 
  • ranked (boolean) – Whether you want to participate in ranked matches or not.
Response JSON Object:
 
  • id (integer) – Your ID.
  • username (string) – Your username.
  • ranked (boolean) – Whether you want to participate in ranked matches or not.
Status Codes:
POST /api/users/me/version

Create a new version of your bot for ranked matches. If no versions exist, this creates version 1, otherwise it increments the last version for your bot.

Example response content:

{
    "id": 1,
    "username": "foouser",
    "version": 10
}
Request Headers:
 
Response JSON Object:
 
  • id (integer) – Your ID.
  • username (string) – Your username.
  • version (integer) – The new version number for your bot.
Status Codes:

Invitation Endpoints

The invitation endpoints allow you to send and receive invitations to play games. Example usage can be seen in the rc_connect script.

GET /api/invitations/

Unaccepted invitations sent to you from other players.

Example response content:

{
    "invitations": [1, 2, 5]
}
Request Headers:
 
Response JSON Object:
 
  • invitations (array<integer>) – id’s of your unaccepted invitations.
Status Codes:
POST /api/invitations/

Send an invitation to another player.

Example request content:

{
    "opponent": "thatguy",
    "color": true
}

Example response content:

{
    "game_id": 1
}
Request Headers:
 
Request JSON Object:
 
  • opponent (string) – The name of the player to send the invitation to.
  • color (boolean) – The color you want to play - true for White and false for Black.
Response JSON Object:
 
  • game_id (integer) – The game ID of the resulting game.
Status Codes:
POST /api/invitations/(int: invitation_id)

Accept the invitation_id invitation.

Example response content:

{
    "game_id": 1
}
Parameters:
  • invitation – The ID of the invitation.
Request Headers:
 
Response JSON Object:
 
  • game_id (integer) – The game ID of the resulting game.
Status Codes:
POST /api/invitations/(int: invitation_id)/finish

Mark the invitation_id invitation as finished.

Parameters:
  • invitation – The ID of the invitation.
Request Headers:
 
Status Codes:

Game Endpoints

The game endpoints allow you to send actions to the server and receive their results. Example usage can be seen in the implementation of reconchess.RemoteGame.

GET /api/games/(int: game_id)/color

Get the color you are playing as in game game_id.

Example response content:

{
    "color": true
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • color (boolean) – The color you are playing as - true for White and false for Black.
Status Codes:
GET /api/games/(int: game_id)/starting_board

Get the starting board for game game_id.

Example response content:

{
    "board": {
        "type": "Board",
        "value": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
    }
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • board (object) – The starting board.
  • type (string) – "Board".
  • value (string) – The fen string of the chess board.
Status Codes:
GET /api/games/(int: game_id)/opponent_name

Get the name of your opponent for game game_id.

Example response content:

{
    "opponent_name": "super evil dude 123"
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • opponent_name (string) – The name of the opponent.
Status Codes:
POST /api/games/(int: game_id)/ready

Mark yourself as ready to start the game.

Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Status Codes:
GET /api/games/(int: game_id)/sense_actions

Get the sense actions you can take. See reconchess.Game.sense_actions().

Example response content:

{
    "sense_actions": [1, 2, 3, 4]
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • sense_actions (array<integer>) – A list of squares you can sense.
Status Codes:
GET /api/games/(int: game_id)/move_actions

Get the move actions you can take. See reconchess.Game.move_actions().

Example response content:

{
    "move_actions": [
        {"type": "Move", "value": "e2e4"},
        {"type": "Move", "value": "a7a8q"}
    ]
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • move_actions (object) – A list of the moves you can make.
  • type (string) – "Move".
  • value (string) – The chess move encoded as a UCI string.
Status Codes:
GET /api/games/(int: game_id)/seconds_left

Gets the number of seconds you have left to play. See reconchess.Game.get_seconds_left().

Example response content:

{
    "seconds_left": 50
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • seconds_left (float) – The time you have left to play.
Status Codes:
GET /api/games/(int: game_id)/opponent_move_results

Get the result of the opponent’s last move. See reconchess.Game.opponent_move_results().

Example response content:

{
    "opponent_move_results": 34
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • opponent_move_results (Optional<integer>) – The square the opponent captured one of your pieces on. null if no capture occurred.
Status Codes:
POST /api/games/(int: game_id)/sense

Perform a sense action. See reconchess.Game.sense().

Example request content:

{
    "square": 5
}

Example response content:

{
    "sense_result": [
        [54, {"type": "Piece", "value": "p"}],
        [55, null],
        [56, {"type": "Piece", "value": "K"}]
    ]
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Request JSON Object:
 
  • square (integer) – The square you want to sense.
Response JSON Object:
 
  • sense_result (object) – The list of squares and pieces found from your sense.
  • type (string) – Piece.
  • value (Optional<string>) – The symbol of the piece found at the square. null if no piece is there.
Status Codes:
  • 200 OK – Success.
  • 400 Bad Request – Game is finished, you already sensed, or malformed request data.
  • 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
  • 404 Not Found – Game does not exist.
POST /api/games/(int: game_id)/move

Perform a move action. See reconchess.Game.move().

Example request content:

{
    "requested_move": {"type": "Move", "value": "e2e4"}
}

Example response content:

{
    "move_result": [
        {"type": "Move", "value": "e2e4"},
        null,
        23
    ]
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Request JSON Object:
 
  • requested_move (object) – The move you want to perform.
Response JSON Object:
 
  • move_result (object) – The result of your move, a list containing the requested_move, the taken_move, and the capture square if one occurred.
  • type (string) – Move.
  • value (Optional<string>) – The move encoded as a UCI string. null if no piece is there.
Status Codes:
  • 200 OK – Success.
  • 400 Bad Request – Game is finished, you haven’t sensed, you already moved, or malformed request data.
  • 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
  • 404 Not Found – Game does not exist.
POST /api/games/(int: game_id)/end_turn

End your turn. See reconchess.Game.end_turn().

Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Status Codes:
GET /api/games/(int: game_id)/is_over

Whether the game is over. See reconchess.Game.is_over().

We recommend using the game_status endpoint for turn management.

Example response content:

{
    "is_over": true
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • is_over (boolean) – Whether the game is over.
Status Codes:
POST /api/games/(int: game_id)/resign

Resign from the game. Can only be called during your turn.

Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Status Codes:
POST /api/games/(int: game_id)/error_resign

Tell the server that you have errored out. This just zeros out any time you have remaining instead of waiting for the time to run out.

Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Status Codes:
GET /api/games/(int: game_id)/is_my_turn

Whether it is your turn to play.

We recommend using the game_status endpoint for turn management.

Example response content:

{
    "is_my_turn": true
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • is_my_turn (boolean) – Whether it is your turn to play.
Status Codes:
GET /api/games/(int: game_id)/game_status

A combination of the is_over and is_my_turn endpoints.

Example response content:

{
    "is_my_turn": true,
    "is_over": false
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • is_my_turn (boolean) – Whether it is your turn to play.
  • is_over (boolean) – Whether the game is over.
Status Codes:
GET /api/games/(int: game_id)/winner_color

The color of the winner of the game. See reconchess.Game.get_winner_color().

Example response content:

{
    "winner_color": true
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • winner_color (Optional<boolean>) – The color of the player that one the game - true for White, false for Black, and null for a draw.
Status Codes:
GET /api/games/(int: game_id)/win_reason

The reason the game ended. See reconchess.Game.get_win_reason() and reconchess.WinReason.

Example response content:

{
    "win_reason": {
        "type": "WinReason",
        "value": "KING_CAPTURE"
    }
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • win_reason (Optional<WinReason>) – The reason the game ended.
  • type (string) – WinReason.
  • value (string) – The string version of the values of reconchess.WinReason. null if a draw.
Status Codes:
GET /api/games/(int: game_id)/game_history

The history of the game. See reconchess.Game.get_game_history() and reconchess.GameHistory.

Example response content:

{
    "game_history": {
        "type": "GameHistory",
        "senses": {
            "true": [55],
            "false": [null]
        },
        "sense_results": {
            "true": [
                [
                    [54, {"type": "Piece", "value": "p"}],
                    [55, null],
                    [56, {"type": "Piece", "value": "K"}]
                ]
            ],
            "false": [[]]
        },
        "requested_moves": {
            "true": [{"type": "Move", "value": "e2e4"}],
            "false": [{"type": "Move", "value": "e7e8"}]
        },
        "taken_moves": {
            "true": [{"type": "Move", "value": "e2e4"}],
            "false": [null]
        },
        "capture_squares": {
            "true": [23],
            "false": [null]
        },
        "fens_before_move": {
            "true": ["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"],
            "false": ["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"]
        },
        "fens_after_move": {
            "true": ["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"],
            "false": ["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"]
        }
    }
}
Parameters:
  • game_id – The ID of the game.
Request Headers:
 
Response JSON Object:
 
  • game_history (object) – The game history object.
  • type (string) – The type of the object.
  • value (string) – The value of the object.
  • senses (object) – An object containing the senses for each player.
  • sense_results (object) – An object containing the sense_results for each player.
  • requested_moves (object) – An object containing the requested_moves for each player.
  • taken_moves (object) – An object containing the taken_moves for each player.
  • capture_squares (object) – An object containing the capture_squares for each player.
  • fens_before_move (object) – An object containing the fens_before_move for each player.
  • fens_after_move (object) – An object containing the fens_after_move for each player.
Status Codes: