Game Management

Joining the Lobby

Users must call /api/lobby/join to become visible to other players.
The server response includes a keepAliveBefore timestamp, after which the client must rejoin to remain visible.

POST /api/lobby/join
Authorization: Bearer <token>
X-Wizard-Client-Type: <your-client-id>
{
  "wizardId": "string",
  "playerName": "string",
  "clientType": "string"
}

Response:

{
  "availablePlayers": [
    {
      "playerId": "string",
      "name": "string",
      "lastSeen": "2025-04-25T19:30:03.488Z"
    }
  ],
  "invites": [
    {
      "inviteId": "string",
      "gameId": "string",
      "invitedBy": {
        "playerId": "string",
        "name": "string"
      },
      "inviteCreatedAt": "2025-04-25T19:30:03.488Z",
      "inviteExpiresAt": "2025-04-25T19:30:03.488Z"
    }
  ],
  "keepAliveBefore": "2025-04-25T19:30:03.488Z",
  "myUser": {
    "playerId": "string",
    "name": "string"
  },
  "myGames": [
    "string"
  ]
}

The player must continuously be kept alive in the lobby.
Call the /api/lobby/keepalive endpoint to refresh the player's state

Creating a Game

Once in the lobby, a user can create a game and invite others by calling:

POST /api/game/start
Authorization: Bearer <token>
X-Wizard-Client-Type: <your-client-id>
{
  "gameName": "string",
  "playerIds": [
    "string"
  ]
}

Invites will show up in subsequent /api/lobby/keepalive responses.
After all invited players have accepted, the game is started automatically.
To start playing, one of the players must create the first round

Responding to invites

Invites can be accepted or rejected by the player of your client.
Call the respective endpoint to respond to an invitation.
Replace the {inviteId} by the ID found in the invite.

GET /api/lobby/invite/{inviteId}/accept
Authorization: Bearer <token>
X-Wizard-Client-Type: <your-client-id>

GET /api/lobby/invite/{inviteId}/reject
Authorization: Bearer <token>
X-Wizard-Client-Type: <your-client-id>

Response:

{
  "id": "string",
  "gameId": "string",
  "playerId": "string",
  "playerName": "string",
  "inviteState": "Invited"
}

Game details

At any time, the details of a card game can be fetched from the API.
Replace the gameId by the ID of the current game.

GET /api/game/{gameId}
Authorization: Bearer <token>
X-Wizard-Client-Type: <your-client-id>

{
  "gameId": "string",
  "gameName": "string",
  "players": [
    {
      "playerId": "string",
      "name": "string",
      "joinState": "Invited"
    }
  ],
  "maxRounds": 1073741824,
  "rounds": [
    {
      "id": "string",
      "roundNumber": 1073741824,
      "winEstimates": [
        {
          "playerId": "string",
          "name": "string",
          "estimate": 1073741824
        }
      ],
      "dominantCard": {
        "color": "string",
        "value": 1073741824
      },
      "handsCompleted": 1073741824,
      "roundCompleted": true,
      "nextAction": {
        "action": "EstimateWins",
        "playerId": "string",
        "name": "string"
      },
      "roundScore": [
        {
          "playerId": "string",
          "name": "string",
          "score": 1073741824
        }
      ]
    }
  ],
  "totalScore": [
    {
      "playerId": "string",
      "name": "string",
      "score": 1073741824
    }
  ],
  "gameEnded": true
}

Lobby and Game Creation Flow

flowchart LR
    A[Join Lobby] --> B[Receive deadline timestamp]
    B --> C[Create Game]
    C --> D[Send Invites]
    D --> E[Players Accept]
    E --> F[Start Round]