Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Antonelli-Tech-Solutions/spades/llms.txt

Use this file to discover all available pages before exploring further.

Any authenticated player can create a table. The creating player immediately becomes the host and is automatically seated in the north seat. The other three seats (east, south, west) start empty and can be filled by other players, bots, or a mix of both. A game begins automatically once all four seats are occupied.

​
POST /api/tables

Required headers
HeaderDescription
x-session-idSession token from login
x-player-idAuthenticated player’s UUID
Request body All fields are optional. When omitted, sensible defaults are applied (see each field below).
​
name
string
Display name for the table. Maximum 50 characters. Leading and trailing whitespace is trimmed. If omitted or empty, a default name is used and the field is stored as null.
​
visibility
string
Controls who can discover this table. Must be one of "public", "friends-only", or "private". Defaults to "public".
  • public — listed in the lobby browser and visible to all players.
  • friends-only — visible only in the friends list of the host’s friends; not listed in the public lobby.
  • private — completely unlisted; accessible only via a direct join link or in-app invite.
​
joinPolicy
string
Controls who is allowed to sit at the table. Must be one of "open", "friends-only", or "invite-only". Must be compatible with the chosen visibility (see the compatibility table below). If omitted, defaults to the most permissive policy allowed by the visibility. An incompatible value is rejected with 400.
​
spectating
boolean
Whether spectators may observe the game. Defaults to true. Must be a JSON boolean (true or false), not a string.

​
Visibility / join policy compatibility

The joinPolicy must be compatible with the selected visibility. Sending an incompatible combination returns 400.
VisibilityAllowed join policiesDefault join policy
publicopen, friends-only, invite-onlyopen
friends-onlyfriends-only, invite-onlyfriends-only
privateinvite-onlyinvite-only

​
Visibility explained

The table appears in the lobby browser (GET /api/lobby/tables) and is discoverable by any authenticated player. When a public table is created or updated, a TABLE_CREATED / TABLE_UPDATED WebSocket event is broadcast on the shared lobby channel, so all connected clients see it in real time.
Example request 
curl -X POST http://localhost:3000/api/tables \
  -H 'Content-Type: application/json' \
  -H 'x-session-id: <sessionId>' \
  -H 'x-player-id: <playerId>' \
  -d '{"name": "Alice Table", "visibility": "public", "joinPolicy": "open", "spectating": true}'
Responses
​
201
object
Table created successfully. The host is already seated at north.
​
400
object
Invalid request. Possible causes: name exceeds 50 characters, visibility is not a recognised value, joinPolicy is not a recognised value or is incompatible with the chosen visibility, or spectating is not a boolean. Body: { "error": "..." }.
​
401
object
Missing or invalid session. Body: { "error": "..." }.
Example response 
{
  "tableId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Alice Table",
  "visibility": "public",
  "joinPolicy": "open",
  "spectating": true
}
Tables are stored in Redis with a one-hour inactivity TTL. Any activity on the table (a player sitting, a card played, etc.) resets the TTL. An idle table that receives no activity for one hour is automatically expired and removed from the lobby index.

Build docs developers (and LLMs) love

Get started for freeTalk to us