Player Profiles: Avatar, Career Stats, and Game History

Every Spades Online player has a public profile that is readable by anyone without authentication. Profiles include the player’s display name, chosen avatar icon, table cosmetics, career win/loss record, and a history of their last 20 completed games. No session headers are required to read a profile.

`GET /api/profile/:playerId`

Fetch the public profile for any player by their UUID.

playerId

string

required

UUID of the player whose profile you want to retrieve.

No authentication required. Example request

curl http://localhost:3000/api/profile/550e8400-e29b-41d4-a716-446655440000

Response 200

playerId

string

UUID that uniquely identifies this player.

username

string

The player’s display name as shown in-game and in the lobby.

avatar

object

The player’s selected avatar.

Show avatar fields

icon

number

Numeric ID of the selected avatar icon. Values 1–8 correspond to the 8 built-in default icons.

cosmetics

object

The player’s active table cosmetic settings.

Show cosmetics fields

feltColor

string

Color of the felt table surface. One of green, navy, burgundy, or charcoal.

cardBack

string

Card back design. One of standard-red, standard-blue, or minimal.

career

object

All-time win/loss record across completed games.

Show career fields

wins

number

Total number of games won.

losses

number

Total number of games lost.

recentGames

array

The player’s last 20 completed games, ordered most recent first.

Show recentGames[n] fields

gameId

string

UUID of the completed game.

playedAt

string

ISO 8601 timestamp of when the game completed.

won

boolean

true if this player’s partnership won the game.

scoreNs

number

Final score for the North–South partnership.

scoreEw

number

Final score for the East–West partnership.

seat

string

The seat this player occupied: north, east, south, or west.

Full example response

{
  "playerId": "uuid",
  "username": "alice",
  "avatar": { "icon": 3 },
  "cosmetics": { "feltColor": "green", "cardBack": "standard-red" },
  "career": { "wins": 10, "losses": 5 },
  "recentGames": [
    {
      "gameId": "uuid",
      "playedAt": "2026-03-01T12:00:00Z",
      "won": true,
      "scoreNs": 260,
      "scoreEw": 150,
      "seat": "north"
    }
  ]
}

Status	Meaning
`200`	Profile found. Body: `{ playerId, username, avatar, cosmetics, career, recentGames }`
`400`	`playerId` path parameter is not a valid UUID
`404`	No player found with this UUID

Cosmetics Reference

The following options are available for player cosmetics.

Setting	Available Options
`feltColor`	`green`, `navy`, `burgundy`, `charcoal`
`cardBack`	`standard-red`, `standard-blue`, `minimal`
Avatar `icon`	`1` – `8` (numeric IDs for the 8 default icons)

Authentication

Tables & Lobby

Game Actions

Social

WebSocket

Player Profiles: Avatar, Career Stats, and Game History

`GET /api/profile/:playerId`

Response 200

Cosmetics Reference

Build docs developers (and LLMs) love

Authentication

Tables & Lobby

Game Actions

Social

WebSocket

Documentation Index

​GET /api/profile/:playerId

​Response 200

​Cosmetics Reference

Build docs developers (and LLMs) love

`GET /api/profile/:playerId`

Response 200

Cosmetics Reference