Leaderboard | Achievements API Reference

POST /api/achievements/leaderboard.php

Authorization: AppID:AppKey or user session token

Request body

Field	Type	Required	Description
app_id	string	optional	Filter by app. Omit for platform-wide ranking (total XP across all apps)
scope	string	optional	`global` (default) or `friends`
limit	int	optional	Number of entries (1–100). Default: `50`
offset	int	optional	Skip first N results for pagination (global scope only)

Friends scope — identify the user (when auth is AppID:AppKey — one of)

Field	Type	Description
user_id	int	Numeric user ID
userkey	string	User's `userKey`
token	string	User's session token

When authenticated with a user token in the header, scope=friends works without extra body fields.

Test this endpoint

Headers

Authorization *

Body

app_id

scope

limit

offset

Success response 200

{
  "success": true,
  "scope": "global",
  "app_id": "com.myapp.game",
  "count": 10,
  "entries": [
    {
      "rank": 1,
      "id": 10,
      "username": "champion",
      "name": "Champion",
      "profileimg": "https://...",
      "idverify": 1,
      "xp_total": 8500,
      "achievements_count": 28
    },
    {
      "rank": 2,
      "id": 42,
      "username": "vanelton",
      "name": "Vanelton",
      "profileimg": "https://...",
      "idverify": 1,
      "xp_total": 3500,
      "achievements_count": 12
    }
  ],
  "my_position": null
}

{
  "success": true,
  "scope": "friends",
  "app_id": "com.myapp.game",
  "count": 4,
  "entries": [
    { "rank": 1, "id": 10, "username": "friend1", "xp_total": 3500, "achievements_count": 12 },
    { "rank": 2, "id": 42, "username": "me",      "xp_total": 1200, "achievements_count": 5  },
    { "rank": 3, "id": 11, "username": "friend2", "xp_total": 400,  "achievements_count": 2  }
  ],
  "my_position": {
    "rank": 7,
    "xp_total": 1200,
    "achievements_count": 5,
    "app_id": "com.myapp.game"
  }
}

Response fields

Field	Description
entries[].rank	Real position in the ranking (reflects offset)
entries[].xp_total	Total XP from achievements in the queried scope
entries[].achievements_count	Number of unlocked achievements (used as tiebreaker)
my_position	Authenticated user's position. Always reflects global rank even in friends scope. `null` when auth is AppID:AppKey without a user identifier.

Pagination

// Page 1
{ "app_id": "com.myapp.game", "limit": 20, "offset": 0 }   // ranks 1–20
// Page 2
{ "app_id": "com.myapp.game", "limit": 20, "offset": 20 }  // ranks 21–40

Notes

Users with 0 achievements do not appear in global scope. In friends scope, friends with 0 achievements appear with xp_total: 0.
Ties in XP are broken by achievements_count DESC.