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.

The friends system lets players connect with each other, see each other’s online/in-game/offline presence status, and navigate directly to a friend’s active table as an observer. All endpoints listed on this page require the x-session-id and x-player-id request headers for authentication.

​
GET /api/players/search

Search for players by username prefix before sending a friend request.
​
username
string
required
Case-insensitive prefix to match against player usernames. Maximum 50 characters. Returns up to 20 results ordered alphabetically. The requesting player is always excluded from results.
Response 200 
{
  "players": [
    { "playerId": "uuid", "username": "alice" }
  ]
}
StatusMeaning
200Players found (may be an empty array). Body: { players: [{ playerId, username }] }
400username query parameter is missing or blank
401Missing or invalid session
This endpoint is rate limited. Repeated searches in a short window may return 429 Too Many Requests.

​
Friend Requests

​
POST /api/friends/request

Send a friend request to another player. On success, a FRIEND_REQUEST_RECEIVED WebSocket notification is published to the recipient’s personal notification channel. Headers: x-session-id, x-player-id Request body 
{ "playerId": "<uuid>" }
StatusMeaning
201Friend request sent. FRIEND_REQUEST_RECEIVED published to recipient’s notification channel.
400playerId is not a valid UUID, or you are attempting to friend yourself
401Missing or invalid session
403Either player has blocked the other
404Target player not found
409Already friends, or a request is already pending

​
POST /api/friends/accept

Accept a pending incoming friend request. On success, a FRIEND_REQUEST_ACCEPTED notification is published to the original requester’s personal notification channel. If either player hosts a friends-only table, a TABLE_CREATED notification is sent to the new friend’s channel for each such table. Headers: x-session-id, x-player-id Request body 
{ "playerId": "<uuid>" }
The playerId is the requester’s UUID — the player whose pending request you want to accept.
StatusMeaning
200Request accepted. FRIEND_REQUEST_ACCEPTED published to requester’s notification channel. TABLE_CREATED sent for each friends-only table hosted by either player.
400playerId is not a valid UUID
401Missing or invalid session
403Either player has blocked the other
404No pending friend request found from this player

​
POST /api/friends/decline

Decline a pending incoming friend request. The friendship row is deleted from the database; no notification is sent. Headers: x-session-id, x-player-id Request body 
{ "playerId": "<uuid>" }
The playerId is the requester’s UUID — the player whose pending request you want to decline.
StatusMeaning
200Request declined and friendship row deleted
400playerId is not a valid UUID
401Missing or invalid session
403Either player has blocked the other
404No pending friend request found from this player

​
List Friends

​
GET /api/friends

Returns two arrays: friends (accepted friendships enriched with live presence and table info) and pending (incoming requests awaiting your response). Pending entries are not enriched with presence or table data. Headers: x-session-id, x-player-id Response 200
​
friends
array
Array of accepted friendships, each enriched with presence and table visibility data.
​
pending
array
Array of incoming friend requests awaiting your acceptance or decline.
tableName disclosure rules: Public tables always disclose the table name. Friends-only tables disclose the name only when the requesting player is also a friend of the table host. Private tables — and tables whose data has expired or is missing — always return tableName: null.
StatusMeaning
200Body: { friends: [...], pending: [...] }
401Missing or invalid session

​
Remove a Friend

​
DELETE /api/friends/:playerId

Removes an accepted friendship. Both directions of the friendship record are deleted. If either player hosts a friends-only table, a TABLE_REMOVED notification is sent to the other player’s personal notification channel for each such table. Headers: x-session-id, x-player-id
StatusMeaning
200Friend removed. TABLE_REMOVED sent for each affected friends-only table.
400:playerId is not a valid UUID
401Missing or invalid session
404Friendship not found

​
Table Navigation

​
GET /api/friends/:friendId/table

Checks whether a friend is currently at a table that is visible to the requester, and indicates whether the “Go to Table” action is available based on the table’s spectating setting and join policy. Headers: x-session-id, x-player-id Response 200 
{
  "table": {
    "tableId": "uuid",
    "name": "Alice's Table",
    "hostPlayerId": "uuid",
    "status": "playing",
    "visibility": "public",
    "spectating": true
  },
  "canGoToTable": true
}
Returns { "table": null, "canGoToTable": false } when the friend is not at a table or the table is not visible to the requester.
StatusMeaning
200Body: { table: { tableId, name, hostPlayerId, status, visibility, spectating } | null, canGoToTable: boolean }
401Missing or invalid session
403Not friends with this player

​
POST /api/friends/:friendId/go-to-table

Navigates to a friend’s table as an observer. The table must be visible to the requester and either spectating must be enabled or the requester must have seating rights under the table’s join policy. On success, an OBSERVER_JOINED event is broadcast to the table room. Headers: x-session-id, x-player-id Response 200 
{ "tableId": "uuid" }
StatusMeaning
200Successfully arrived at the table as an observer. Body: { tableId }. OBSERVER_JOINED broadcast to table room.
401Missing or invalid session
403Not friends with this player, table is not visible, or no permission to join as observer
404Friend is not currently at a table
409Observer slots are full, or concurrent modification — retry the request

Build docs developers (and LLMs) love

Get started for freeTalk to us