Players

Reading a player's profile and rank, and changing nicknames.

Get a player's profile

GET /players/{playerId}/profile

curl "https://api.cheddaboards.com/players/dev_1730000000_1a2b3c4d/profile" \
  -H "X-API-Key: cb_my-game_xxxxxxxxx" \
  -H "X-Game-ID: my-game"

{
  "ok": true,
  "data": {
    "nickname": "PlayerName",
    "created": 1788570532131407400,
    "gameProfile": {
      "score": 1234,
      "streak": 3,
      "achievements": ["first_win", "combo_10"],
      "playCount": 2,
      "lastPlayed": 1788571122315540500
    }
  }
}

The gameProfile holds the player's bests and totals for this game: score and streak (independent maxima), playCount, and the achievements they've unlocked — so this one call also gives you their achievements, no separate request needed. created and lastPlayed are nanosecond timestamps (divide by 1,000,000 for JavaScript milliseconds).

For a signed-in player, the equivalent is GET /auth/profile using the session token instead of the API key.

Get a player's rank

Two endpoints, depending on how the player is identified.

Any player, game-wide (works with the API key, so anonymous players too):

GET /players/{playerId}/rank?sort={score|streak}

curl "https://api.cheddaboards.com/players/dev_1730000000_1a2b3c4d/rank?sort=score" \
  -H "X-API-Key: cb_my-game_xxxxxxxxx" \
  -H "X-Game-ID: my-game"

{"ok":true,"data":{"rank":40,"score":1234,"streak":3,"totalPlayers":68}}

This is what the SDKs' get_player_rank() / GetPlayerRank() call. sort is score (default) or streak.

Signed-in player, on a specific board:

GET /games/{gameId}/scoreboards/{scoreboardId}/rank

Returns the player's position on one board — all-time, a timed board, or a category board. This call is keyed on the player's session (send X-Session-Token), and it ranks against the actual board the player sees, so the rank and total match the visible leaderboard. Use it to show "you're #40 of 68" on a given board without pulling the whole thing. (SDK: get_scoreboard_rank() / GetScoreboardRank().)

Change a nickname

Two endpoints, depending on how the player is identified:

PUT /players/{playerId}/nickname     # anonymous — body: { "nickname": "..." }
PUT /profile/nickname                # signed-in — X-Session-Token, body: { "nickname": "..." }

The rule is the same on both: 3–16 characters, letters, digits, and underscores (A–Z a–z 0–9 _).

• A taken name isn't an error on these two endpoints — it's auto-suffixed (Chedz → Chedz_1) and the response reports the name actually applied. (A nickname carried on a score submit behaves differently: see Player names.)
• A genuinely invalid name is rejected with one of: Nickname must be at least 3 characters, Nickname must be 16 characters or less, Nickname can only contain letters, numbers, and underscores. That rejection is permanent for that value — ask for a different name rather than retrying.

An anonymous player must exist server-side before a rename sticks

An anonymous player isn't created on the backend until their first score submit — before that there's no server record for the nickname endpoint to update. Two clean ways to name a brand-new player: include nickname in their first score submit (if that name is free the profile is created with it; if it's taken the profile is created as Player_1248 instead, with no suffixing on this path), or let the server assign the generated name and offer a rename once the first score has landed. The official SDKs (Godot 2.2.7+, Unity 2.3.0+) hold a pre-profile rename locally, send it with the first submit, and if the profile that loads afterwards shows a different name (the chosen one was taken), re-send the rename so the player ends up with the suffixed version rather than Player_N. The full picture, with copy-paste name-entry flows, is on Player names.

Identity, briefly

playerId is the player's private identifier — the dev_<unixtime>_<random> ID your game generates for anonymous players, or the account behind a signed-in one. It's never shown to other players; only the nickname is public. The conceptual picture is in Players and accounts.

See also: Scores · Authentication · What's stored · Errors