Looking to get started quickly?
Go to Quick Start →SDKs
Official client libraries to help you integrate Rankora faster. More coming soon.
Rankora API Documentation
Complete guide to integrate Rankora's leaderboard API service into your application.
Authentication
Bearer Token Required
All API requests must include a valid Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_KEY_HERENever expose your API key in client-side code if you're using this API from a frontend application.
Anyone with access to your API key can submit, delete, or fetch entries from your leaderboard.
Base URL
https://www.rankora.dev/api/v1API Endpoints
Get API Usage
/usageRetrieve the remaining API usage limits for your API key.
Response Example
{
"currentRequests": 150,
"remainingRequests": 850,
"currentLeaderboards": 5,
"remainingLeaderboards": 45,
"currentEntries": 1200,
"remainingEntries": 8800
}Code Examples
1const response = await fetch('https://www.rankora.dev/api/v1/usage', {
2 method: 'GET',
3 headers: {
4 'Authorization': 'Bearer YOUR_API_KEY_HERE',
5 'Content-Type': 'application/json'
6 }
7});
8const data = await response.json();
9console.log(data);Get Leaderboard Metadata
/leaderboardGet metadata information about your leaderboard.
Response Example
{
"id": "d5e1fc9e-461c-4328-a2bd-c033d7a33b37",
"name": "Rankora Leaderboard 1",
"sort_order": "desc"
}Code Examples
1const response = await fetch('https://www.rankora.dev/api/v1/leaderboard', {
2 method: 'GET',
3 headers: {
4 'Authorization': 'Bearer YOUR_API_KEY_HERE'
5 }
6});
7const data = await response.json();
8console.log(data);Get Leaderboard Entries
/leaderboard/entriesRetrieve the top entries from your leaderboard with pagination support.
Query Parameters
limitNumber of entries to return (default: 10, max: 100)offsetNumber of entries to skip (default: 0)orderSort order: "asc" or "desc" (defaults to your leaderboard's current sort setting.To update it, navigate to Dashboard > Leaderboards > Manage)
Response Example
{
"entries": [
{ "name": "PlayerOne", "score": 9500, "metadata": null, "updated_at": "2025-07-21T19:22:47.782875+00:00"},
{ "name": "PlayerTwo", "score": 8750, "metadata": { "other": "value" }, "updated_at": "2025-07-21T12:12:41.623156+00:00" }
],
"pagination": { "limit": 10, "offset": 0, "total": 156 }
}Code Examples
1const params = new URLSearchParams({
2 limit: '10',
3 offset: '0',
4 order: 'desc'
5});
6const response = await fetch(`https://www.rankora.dev/api/v1/leaderboard/entries?${params}`, {
7 headers: {
8 'Authorization': 'Bearer YOUR_API_KEY_HERE'
9 }
10});
11const data = await response.json();
12console.log(data.entries);Create or Update Entry
/leaderboard/entriesCreate a new entry or update an existing one. If player_id is provided, the entry will be updated.
Request Body
{
"name": "string",
"score": "number",
"player_id": "string (optional)",
"metadata": {
"key1": "value1",
"key2": "value2"
}
}Metadata Usage
Metadata is only available on "Indie" or higher plans.
Metadata Validation Rules
- Maximum 10 metadata keys
- Maximum key length: 32 characters
- Maximum value length: 64 characters
Response Example
{
"success": true,
"player_id": "929f5200-0d3a-436c-b54b-eb281bf6b41a"
}Code Examples
1const entry = {
2 name: 'PlayerOne',
3 score: 1200,
4 player_id: 'optional-player-id',
5 metadata: {
6 character: 'wizard',
7 level: '12'
8 }
9};
10
11const response = await fetch('https://www.rankora.dev/api/v1/leaderboard/entries', {
12 method: 'POST',
13 headers: {
14 'Authorization': 'Bearer YOUR_API_KEY_HERE',
15 'Content-Type': 'application/json'
16 },
17 body: JSON.stringify(entry)
18});
19const data = await response.json();
20console.log(data);Get Entry by Player ID
/leaderboard/entries/:player_idRetrieve a specific entry by player_id.
Response Example
{
"leaderboard_id": "d5e1fc9e-461c-4328-a2bd-c033d7a33b37",
"name": "Dummy Test 3",
"score": 12.020123,
"player_id": "929f5200-0d3a-436c-b54b-eb281bf6b41a",
"metadata": { "other": "value" }
"created_at": "2025-07-14T19:19:40.956582+00:00",
"updated_at": "2025-07-21T12:12:41.623156+00:00",
}Code Examples
1const playerId = '929f5200-0d3a-436c-b54b-eb281bf6b41a';
2
3const response = await fetch(`https://www.rankora.dev/api/v1/leaderboard/entries/${playerId}`, {
4 headers: {
5 'Authorization': 'Bearer YOUR_API_KEY_HERE'
6 }
7});
8const data = await response.json();
9console.log(data);Delete Entry by Player ID
/leaderboard/entries/:player_idPermanently remove a leaderboard entry associated with the provided player_id.
Path Parameters
player_idUnique identifier of the player entry to delete.Response Example
{
"success": true
}Code Examples
1await fetch("https://www.rankora.dev/api/v1/leaderboard/entries/PLAYER_ID", {
2 method: "DELETE",
3 headers: {
4 Authorization: "Bearer YOUR_API_KEY_HERE",
5 },
6});Error Handling
The API uses standard HTTP status codes to indicate success or failure of requests.
200 OK: Request succeeded400 Bad Request: Invalid request data401 Unauthorized: Missing or invalid API key403 Forbidden: Access denied for this resource404 Not Found: Resource not found429 Too Many Requests: Rate limit exceeded500 Internal Server Error: Server encountered an error
Rate Limits
API usage is limited based on your subscription plan. Monitor your usage with the /usage endpoint.
free plan
- Monthly API requests: 7,500
- Requests per minute: 120
- Max leaderboards: 2
- Max entries per leaderboard: 500
starter plan
- Monthly API requests: 50,000
- Requests per minute: 500
- Max leaderboards: 6
- Max entries per leaderboard: 4,000
pro plan
- Monthly API requests: 300,000
- Requests per minute: 1500
- Max leaderboards: 500
- Max entries per leaderboard: 100,000
💡 Tip: When you exceed your rate limits, you'll receive a 429 status code. Consider implementing exponential backoff in your client code.