Rankora API Quick Start

Get up and running with Rankora in minutes. Learn the basics of creating leaderboards and submitting scores.

Overview

This quick start guide will walk you through the essential steps to integrate Rankora leaderboards into your application. You'll learn how to authenticate, submit scores, and retrieve leaderboard data.

Estimated time: 5-10 minutes

Prerequisites

API Key

Get your API key from the Rankora dashboard. This is required for all API requests.

HTTP Client

Any HTTP client (cURL, Postman, or your programming language's HTTP library).

Base URL

All Rankora API endpoints use this base URL:

text

https://www.rankora.dev/api/v1

Authentication

Include your API key using either the Authorization header:

Bearer Tokenhttp

Authorization: Bearer YOUR_API_KEY_HERE

Security Note: Keep your API key secure and never expose it in client-side code or public repositories.

Create or Update Entry

Add a new leaderboard entry or update an existing one by sending a POST request. If you provide a player_id, it will update an existing entry; otherwise, a new one will be created:

http

POST /leaderboard/entries
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "name": "PlayerOne",
  "score": 12345,
  "player_id": "optional-player-id",
  // metadata only available on Indie or higher plans
  "metadata": {
    "key1": "value1"
  }
}

Response:

json

{
  "success": true,
  "player_id": "player-id",
  "rank": 32
}

Note: The response includes the player's current rank. If you provide a player_id that already exists, the entry will be updated with the new score.

Get Leaderboard Entries

Retrieve top leaderboard entries with optional pagination. Responses are cached for 5 seconds to improve performance:

http

GET /leaderboard/entries?limit=5&offset=0&order=desc
Authorization: Bearer YOUR_API_KEY_HERE

Common Query Parameters

limitNumber of entries (default: 5, max: 50)

offsetNumber of entries to skip

orderSort order: "asc" or "desc"

Response:

json

{
  "entries": [
    { 
      "name": "PlayerOne", 
      "score": 9500, 
      "rank": 1,
      "updated_at": "2025-07-21T19:22:47.782875+00:00", 
      "metadata": null 
    },
    { 
      "name": "PlayerTwo", 
      "score": 8750, 
      "rank": 2,
      "updated_at": "2025-07-21T12:12:41.623156+00:00", 
      "metadata": { "other": "value" } 
    }
  ],
  "pagination": { "limit": 5, "offset": 0, "total": 156 }
}

Common Issues & Solutions

401 Unauthorized

Check that your API key is correct and included in the request header.

Solution: Verify your API key in the dashboard and ensure it's properly formatted.

400 Bad Request

Usually caused by invalid data format or missing required fields.

Solution: Ensure all required fields are present and data types are correct.

Pro Tips

Start with small limits (5-10) when testing pagination
Check the /usage endpoint to monitor your API consumption
Implement exponential backoff for rate limit handling

Next Steps

Full Documentation

Explore the complete API reference with detailed examples, error handling, and advanced features.

View Full Docs

SDKs & Libraries

Use official client libraries for Unity, Godot, and other platforms to integrate faster.

Browse SDKs

Try It Out

Test with cURL

Replace YOUR_API_KEY_HERE with your actual API key:

bash

# Get leaderboard entries
curl -X GET "https://www.rankora.dev/api/v1/leaderboard/entries?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

# Submit a score
curl -X POST "https://www.rankora.dev/api/v1/leaderboard/entries" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"name": "TestPlayer", "score": 1000}'