Skip to main content
POST
/
user
/
game-ranks
curl -X POST https://teambattles.gg/api/v1/user/game-ranks \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"gameId": "bo6", "mode": "ranked", "sr": 4200, "winstreak": 5}'

{
  "id": "<string>",
  "timestamp": "<string>"
}

​
Permission Required

This endpoint requires game.ranks:read-write on your API key. The user is always the API key owner, derived from the key itself - it is never accepted as a body field, so a key can only write its own ranks. A free (api_free) key receives 403 error_api_feature_required; this requires an api_pro+ plan.

​
Access / Membership Rules

This is a self-write route. The owner is always derived from principal.user._id, so there is no membership or participant gating - the key writes exactly the owner’s own rank. The upsert targets a single (gameId, mode) slot, creating it or overwriting it in place, and forces the rank’s source to "api". The gameId and mode are validated against the playable-game and playlist catalog; junk values are rejected with 400 INVALID_INPUT (re-enforced in the data layer as INVALID_GAME_RANK).

​
Request Body

FieldTypeRequiredDescription
gameIdstringYesGame definition ID to set the rank for (a playable game).
modestringYesGame mode / playlist the rank applies to (a valid playlist ID).
srnumberYesSkill rating (integer, 0-100000).
isTop250booleanNoWhether the player is in the Top 250 ladder.
top250RanknumberNoTop 250 ladder position (1-250); only meaningful when isTop250.
winstreaknumberNoCurrent win streak count (0-99).

​
What’s Returned

Returns an object with the id of the upserted game rank row and a timestamp. Mintlify renders the full schema from the spec below. 
curl -X POST https://teambattles.gg/api/v1/user/game-ranks \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"gameId": "bo6", "mode": "ranked", "sr": 4200, "winstreak": 5}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Body

application/json

Upsert the API key owner's rank for one (gameId, mode) slot.

​
gameId
enum<string>
required

Game definition ID to set the rank for (a playable game).

Available options:
call_of_duty_black_ops_7,
valorant,
league_of_legends,
counter_strike_2
​
mode
string
required

Game mode / playlist the rank applies to (a valid playlist ID).

Required string length: 1 - 64
​
sr
integer
required

Skill rating (integer, 0-100000).

Required range: 0 <= x <= 100000
​
isTop250
boolean

Whether the player is in the Top 250 ladder.

​
top250Rank
integer

Top 250 ladder position (1-250); only meaningful when isTop250.

Required range: 1 <= x <= 250
​
winstreak
integer

Current win streak count (0-99).

Required range: 0 <= x <= 99

Response

The game rank was created or updated.

Result of upserting a game rank.

​
id
string
required

ID of the upserted game rank row.

​
timestamp
string
required

ISO 8601 response timestamp.