Achievements and leaderboards
Unlock achievements, read unlock percentages, find or create leaderboards, upload scores with keep-best or force-update, and read ranked entries globally, around a player or among friends.
#Achievements
A game declares its achievements (with names, display names, descriptions and icons) in its app schema. A player's unlocks are part of their stats document:
curl -s -X PUT https://api.0x.limo/v1/apps/4000009/userstats/$STEAMID \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"achievements": {"FIRST_WIN": 1792250000}}'Each value is the unlock time in Unix seconds. An object {"achieved": true, "unlock_time": 1792250000} is accepted too.
A game server may write the stats of players in its own app with its game-server session.
| Route | Auth | Returns |
|---|---|---|
GET /v1/apps/{appid}/userstats/{steamid} | token | {stats, achievements} |
GET /v1/apps/{appid}/achievement_percentages | token | {players, achievements: [{name, percent}]}, most achieved first |
GET /v1/apps/{appid}/achievements | public | the store page: {appid, total, hidden_count, players, achievements: [{name, display_name, description, icon, icon_gray, percent}]} |
GET /v1/me/apps/{appid}/community | token | the caller's side of the store page: unlocked achievements (hidden ones included), leaderboard ranks |
Hidden achievements are counted on the store page but shown only to the players who unlocked them.
#Leaderboards
#Find or create
curl -s "https://api.0x.limo/v1/apps/4000009/leaderboards/best_lap?create=1&sort=1&display=3" \
-H "Authorization: Bearer $TOKEN"
# {"id": 77, "name": "best_lap", "sort": 1, "display": 3, "entry_count": 1204}create=1creates the board if it doesn't exist. Without it, a missing board answers404 no such leaderboard.sort(only used when creating) is1ascending (lower is better, e.g. times) or2descending.display(only used when creating) is1numeric,2seconds or3milliseconds.
#Upload a score
curl -s https://api.0x.limo/v1/leaderboards/77/scores -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"score": 61840, "details": [3, 1], "method": "keep_best"}'
# {"changed": true, "rank_new": 12, "rank_prev": 30}method is keep_best (the default: only a better score replaces the old one) or force_update.
Scores are 32-bit signed integers (larger values are clamped). details is optional extra data stored with the entry (Steam's score details, a list of integers).
PUT /v1/leaderboards/{id}/ugc {handle} attaches a shared file you committed (a replay, a ghost) to
your entry.
#Read entries
GET /v1/leaderboards/{id}/entries returns ranked entries
[{steamid, score, details, ugc, rank, persona}]. The request parameter picks which entries:
request | Parameters | Entries |
|---|---|---|
| (default) global | start (1), end (10) | ranks start to end |
around_user | user (default: the caller), start (-4), end (5) | ranks relative to the player |
friends | start, end | the caller and their friends, in rank order |
users | users (comma-separated SteamIDs) | those players |
curl -s "https://api.0x.limo/v1/leaderboards/77/entries?request=around_user&start=-2&end=2" \
-H "Authorization: Bearer $TOKEN"#Store page
GET /v1/apps/{appid}/leaderboards (public) lists a listed game's leaderboards, busiest first (at
most 20), each with its top 10 by persona name. It never shows SteamIDs.
See the generated leaderboards reference and apps reference.
