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: - Authorization – Basic Authorization.
Response JSON Object: - usernames (array<string>) – usernames of active users.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
-
POST
/api/users/me
¶ Ping the server to update your connection time.
Example response content:
{ "id": 1, "username": "foouser", "max_games": 4 }
Request Headers: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
-
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: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 400 Bad Request – Invalid request (max_games not present or not an integer).
- 401 Unauthorized – Invalid or empty authentication information.
-
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: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 400 Bad Request – Invalid request (ranked not present or not a boolean).
- 401 Unauthorized – Invalid or empty authentication information.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - id (integer) – Your ID.
- username (string) – Your username.
- version (integer) – The new version number for your bot.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Invalid request (ranked not present or not a boolean).
- 401 Unauthorized – Invalid or empty authentication information.
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: - Authorization – Basic Authorization.
Response JSON Object: - invitations (array<integer>) – id’s of your unaccepted invitations.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
-
POST
/api/invitations/
¶ Send an invitation to another player.
Example request content:
{ "opponent": "thatguy", "color": true }
Example response content:
{ "game_id": 1 }
Request Headers: - Authorization – Basic Authorization.
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 andfalse
for Black.
Response JSON Object: - game_id (integer) – The game ID of the resulting game.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Invitation does not exist.
- 401 Unauthorized – Invalid or empty authentication information.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - game_id (integer) – The game ID of the resulting game.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Invitation does not exist.
- 401 Unauthorized – Invalid or empty authentication information.
-
POST
/api/invitations/
(int: invitation_id)/finish
¶ Mark the invitation_id invitation as finished.
Parameters: - invitation – The ID of the invitation.
Request Headers: - Authorization – Basic Authorization.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Invitation does not exist or invitation is not accepted.
- 401 Unauthorized – Invalid or empty authentication information.
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: - Authorization – Basic Authorization.
Response JSON Object: - color (boolean) – The color you are playing as -
true
for White andfalse
for Black.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - board (object) – The starting board.
- type (string) –
"Board"
. - value (string) – The fen string of the chess board.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - opponent_name (string) – The name of the opponent.
Status Codes: - 200 OK – Success.
- 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)/ready
¶ Mark yourself as ready to start the game.
Parameters: - game_id – The ID of the game.
Request Headers: - Authorization – Basic Authorization.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Player already marked as ready.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - sense_actions (array<integer>) – A list of squares you can sense.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - seconds_left (float) – The time you have left to play.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Game is finished.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 400 Bad Request – Game is finished.
- 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)/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: - Authorization – Basic Authorization.
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: - Authorization – Basic Authorization.
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: - Authorization – Basic Authorization.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Game is finished, you haven’t sensed and moved.
- 401 Unauthorized – Invalid or empty authentication information, or not a player in the specified game.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - is_over (boolean) – Whether the game is over.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Status Codes: - 200 OK – Success.
- 400 Bad Request – It is not your turn.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - is_my_turn (boolean) – Whether it is your turn to play.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - is_my_turn (boolean) – Whether it is your turn to play.
- is_over (boolean) – Whether the game is over.
Status Codes: - 200 OK – Success.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
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: - Authorization – Basic Authorization.
Response JSON Object: - winner_color (Optional<boolean>) – The color of the player that one the game -
true
for White,false
for Black, andnull
for a draw.
Status Codes: - 200 OK – Success.
- 400 Bad Request – Game is not over.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
GET
/api/games/
(int: game_id)/win_reason
¶ The reason the game ended. See
reconchess.Game.get_win_reason()
andreconchess.WinReason
.Example response content:
{ "win_reason": { "type": "WinReason", "value": "KING_CAPTURE" } }
Parameters: - game_id – The ID of the game.
Request Headers: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 400 Bad Request – Game is not over.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.
-
GET
/api/games/
(int: game_id)/game_history
¶ The history of the game. See
reconchess.Game.get_game_history()
andreconchess.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: - Authorization – Basic Authorization.
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: - 200 OK – Success.
- 400 Bad Request – Game is not over.
- 401 Unauthorized – Invalid or empty authentication information.
- 404 Not Found – Game does not exist.