Getting Started

Overview

Real Rate tracks player ratings across competitive game titles. Your game submits results to our API; we handle Elo calculations, leaderboards, and player profiles. Integration requires only two API calls — one to register a player and one to submit a game result.

Create an Account

Go to the registration page and create a user account. This account is your management portal — it is separate from the API credentials your application will use.

Once registered you will be taken to the Manage page where you can create and configure titles.

Create a Title

A title represents your game. From the Manage page, click New Title and fill in:

• Name — the display name of your game.
• Identifier — a short, URL-safe slug (e.g. my-game). This is used in every API call and cannot be changed later.
• Game Types — the competitive modes you want to track separately (e.g. 1v1, team). Each game type maintains its own rating ladder. You can add more game types later from the title settings page.

Get an API Key

Open your title's settings page and scroll to API Clients. Enter a name for your client (e.g. Production Server) and click Generate Key.

You will be shown three values — copy them now, as the key cannot be retrieved again:

• Client ID — the UUID that identifies your API client.
• API Key — the secret credential for that client.
• Authorization Header Value — the pre-built value to use directly in requests (see Step 4).

If a key is ever compromised, click Revoke next to it and generate a new one. Each title can have multiple API clients — useful for separating environments.

Set Up Your Environment

All protected API endpoints require an Authorization header. The value is the Authorization Header Value copied from Step 3. Store it as an environment variable in your server:

# .env / server environment
REALRATE_AUTH=Basic <your-authorization-header-value>

Then include it in every API request:

# Example using curl
curl -X POST https://realrate.gg/player \
  -H "Authorization: $REALRATE_AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "name": "PlayerOne", "title": "my-game" }'

Register Players

Before submitting a game, every participant must be registered as a player in Real Rate. Call POST /player for each player in your game:

POST /player
Authorization: $REALRATE_AUTH
Content-Type: application/json

{
  "name": "PlayerOne",
  "title": "my-game"
}

The response includes the player's id — a UUID you will use when submitting games. There are two strategies for managing these IDs:

// Request — no id field
{
  "name": "PlayerOne",
  "title": "my-game"
}

// Response — save this id
{
  "id": "3fa85f64-...",
  "name": "PlayerOne",
  "title": "my-game"
}

// Request — supply your own UUID
{
  "id": "your-existing-uuid",
  "name": "PlayerOne",
  "title": "my-game"
}

You only need to register a player once. Subsequent game submissions use the player ID directly — no re-registration required.

Submit Games

After a match concludes, call POST /game to record the result and trigger rating updates:

1v1 match

POST /game
Authorization: $REALRATE_AUTH
Content-Type: application/json

{
  "id": "unique-game-uuid",
  "title": "my-game",
  "gameType": "1v1",
  "winner": "winner-player-uuid",
  "loser":  "loser-player-uuid"
}

Team match

POST /game
Authorization: $REALRATE_AUTH
Content-Type: application/json

{
  "id": "unique-game-uuid",
  "title": "my-game",
  "gameType": "team",
  "winners": ["player-uuid-1", "player-uuid-2"],
  "losers":  ["player-uuid-3", "player-uuid-4"]
}

On success, the response includes each player's rating change. If a game ID is submitted twice, the request is rejected — use a deterministic UUID (e.g. derived from your internal match ID) to make retries safe.