Recipes / curl

curl / REST API

Test the API directly from your terminal, or use any HTTP client in any language. No SDK required.

curlPhaserPixiJSGodotUnityUnreal

Prerequisites

  • A LightLeaderboard account and a game created in the portal
  • Your game's API key (generated in Game Settings)
  • curl installed (pre-installed on macOS/Linux; use WSL or Git Bash on Windows)

Submit a Score

POST a score to the scores endpoint. The response immediately includes the player's new rank.

Submit a score
curl -X POST \
  "https://yourapp.com/api/v1/games/my_game/scores" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "score": 42000,
    "playerRefId": "player_001",
    "playerName": "Alice",
    "submissionId": "session_abc123"
  }'
← Response
{ "id": 1847, "rank": 3, "score": 42000, "playerName": "Alice" }
scoreInteger score value
playerRefIdYour internal player ID — never changes
playerNameDisplay name shown on the leaderboard
submissionIdUnique per submission — prevents duplicates

Fetch the Leaderboard

GET the ranked list. Filter by period, season, or team.

Get leaderboard
curl \
  "https://yourapp.com/api/v1/games/my_game/leaderboard?limit=10&period=all" \
  -H "Authorization: Bearer YOUR_API_KEY"
← Response
{
  "entries": [
    { "rank": 1, "playerName": "Bob",   "score": 98000 },
    { "rank": 2, "playerName": "Carol", "score": 75000 },
    { "rank": 3, "playerName": "Alice", "score": 42000 }
  ]
}

Player Rank & Centric View

Get a single player's rank, or fetch the players immediately above and below them.

Player rank
curl \
  "https://yourapp.com/api/v1/games/my_game/players/player_001/rank" \
  -H "Authorization: Bearer YOUR_API_KEY"
Centric view (player in context)
curl \
  "https://yourapp.com/api/v1/games/my_game/players/player_001/centric?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tips

  • Use submissionId to make score submissions idempotent — safe to retry on network failure.
  • Add ?period=weekly or ?period=monthly to the leaderboard URL for time-scoped rankings.
  • Pass seasonId in the score body to support multiple ranked seasons.
  • For server-to-server submissions, add an HMAC-SHA256 signature header — see the Anti-Cheat recipe.
← All Recipes Phaser 3 →