API

Game

Everything about playing: finding an opponent, private rooms, placing ships and shooting.

All endpoints in this section need Authorization: Bearer <token> and return:

{ "game": { ... } }

The game object

The game as you see it. Your opponent’s ships are hidden until they are sunk (or until the game ends).

{
    "id": "66ca0c1fe4b0a1c2d3e4f5b7",
    "status": "playing",
    "private": false,
    "code": null,
    "fleet": [4, 3, 3, 2, 2, 2, 1, 1, 1, 1],
    "you": {
        "nickname": "alice",
        "ready": true,
        "board": "SSSS.o....  ...100 chars",
        "ships": [
            { "x": 0, "y": 0, "length": 4, "vertical": false, "sunk": false }
        ]
    },
    "opponent": {
        "nickname": "bob",
        "ready": true,
        "board": "..o.X#....  ...100 chars",
        "sunkShips": [
            { "x": 5, "y": 0, "length": 1, "vertical": false }
        ]
    },
    "yourTurn": true,
    "timeLeftMs": 27450,
    "lastShot": { "by": "you", "x": 4, "y": 0, "result": "hit" },
    "winner": null,
    "reason": null
}
Field Description
status waiting: looking for an opponent. placing: ship placement. playing: battle. finished: the game is over. cancelled: someone left before the battle.
private / code Private room and its 5-character code (only for private rooms).
fleet Ship lengths every player must place.
you.board Your board with your ships.
you.ships Your ships, with sunk flags.
opponent null while waiting for an opponent.
opponent.board What you know about the opponent’s board. After the game ends, the remaining ships are revealed as S.
opponent.sunkShips The opponent’s ships you have already sunk.
yourTurn true if you should shoot now.
timeLeftMs Milliseconds until the current timer (placement or turn) runs out, null if there is no timer.
lastShot The latest shot by anyone: by is you or opponent, result is miss, hit or sunk.
winner you, opponent or null.
reason Why the game ended: all_sunk, surrender, timeout (too many missed turns), left (cancelled before the battle).

Boards

A board is a string of 100 characters, row by row. The cell (x, y) is at index y * 10 + x.

Char Meaning
. Unknown / empty water
S A ship that hasn’t been hit (only on your own board, or on the opponent’s after the game)
o Miss, or an empty cell revealed around a sunk ship
X Hit: a part of a ship that is still afloat
# A part of a sunk ship

Printing a board in a terminal takes just a few lines:

for y in range(10):
    print(" ".join(board[y * 10:(y + 1) * 10]))

Ships

{ "x": 2, "y": 3, "length": 3, "vertical": true }

(x, y) is the top (or left) cell. A vertical ship goes down, a horizontal one goes right. This ship takes the cells (2,3), (2,4) and (2,5).

Find a random opponent

Joins the queue, or returns the game you are already in.

POST /api/find-game

Private room

Create

POST /api/rooms

Returns a game with status: "waiting", private: true and a code such as "K7MPQ". Give the code to a friend. The room expires after 15 minutes.

Join

POST /api/rooms/join
{ "code": "K7MPQ" }

The code is case-insensitive. The game switches to placing.

Status error
404 Room not found
409 You are already in a game

Current game

GET /api/current-game

Returns { "game": {...} } for your unfinished game, or { "game": null }.

Get a game

GET /api/lobby/:id

Use it to poll the state if you don’t use WebSocket.

Place ships

POST /api/lobby/:id/ready
{
    "ships": [
        { "x": 0, "y": 0, "length": 4, "vertical": false },
        { "x": 0, "y": 2, "length": 3, "vertical": false },
        { "x": 4, "y": 2, "length": 3, "vertical": false },
        { "x": 0, "y": 4, "length": 2, "vertical": false },
        { "x": 3, "y": 4, "length": 2, "vertical": false },
        { "x": 6, "y": 4, "length": 2, "vertical": false },
        { "x": 0, "y": 6, "length": 1 },
        { "x": 2, "y": 6, "length": 1 },
        { "x": 4, "y": 6, "length": 1 },
        { "x": 9, "y": 9, "length": 1 }
    ]
}

Send an empty body {} to get a random fleet. That is the easiest way to start a minimal client.

When both players are ready, the game switches to playing and a random player goes first.

Status error
400 Fleet must contain exactly 10 ships. / Ships must not touch each other. / Ship is out of the board. / …
409 Ships can be placed only before the battle

Shoot

POST /api/lobby/:id/shoot
{ "x": 4, "y": 4 }

Check lastShot.result in the answer. After a hit or a sunk it is still your turn (yourTurn: true).

Status error
400 Cell was already shot. / Cell is out of the board.
409 Not your turn / Battle is not in progress

Leave / surrender

POST /api/lobby/:id/leave

Common errors

| Status | error | |—|—| | 401 | No token provided / Invalid token | | 403 | Not a member of this lobby | | 404 | Lobby not found |