0xDocs 0x.limo

Docs / REST API

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:

bash
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.

RouteAuthReturns
GET /v1/apps/{appid}/userstats/{steamid}token{stats, achievements}
GET /v1/apps/{appid}/achievement_percentagestoken{players, achievements: [{name, percent}]}, most achieved first
GET /v1/apps/{appid}/achievementspublicthe store page: {appid, total, hidden_count, players, achievements: [{name, display_name, description, icon, icon_gray, percent}]}
GET /v1/me/apps/{appid}/communitytokenthe 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

bash
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=1 creates the board if it doesn't exist. Without it, a missing board answers 404 no such leaderboard.
  • sort (only used when creating) is 1 ascending (lower is better, e.g. times) or 2 descending.
  • display (only used when creating) is 1 numeric, 2 seconds or 3 milliseconds.

#Upload a score

bash
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:

requestParametersEntries
(default) globalstart (1), end (10)ranks start to end
around_useruser (default: the caller), start (-4), end (5)ranks relative to the player
friendsstart, endthe caller and their friends, in rank order
usersusers (comma-separated SteamIDs)those players
bash
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.