Documentation

REST API Reference

RESTful API for integrating Team Up leaderboard data into your applications

🔔

Need real-time updates? This API is for fetching data on demand. If you want to receive automatic notifications when matches are recorded or ratings change, check out Webhooks instead.

Quick Start

Get Your API Key

Generate an API key for your Discord server using the /settings api_key command. Keys are server-specific and grant access to that server's data.

/settings api_key generate

Make Your First Request

Use standard REST conventions with your guild ID in the path. Include your API key in the X-API-Key header for protected endpoints.

curl https://api.teamupgg.com/server/YOUR_GUILD_ID/players/PLAYER_ID/rating \
  -H "X-API-Key: your_api_key_here"

Handle the Response

Responses are standard JSON with raw rating data. Use separate endpoints for player names and ranks.

{
  "player_id": "123456789012345678",
  "leaderboard": "ranked",
  "format": "2v2",
  "elo": 1523,
  "matches": 47,
  "wins": 28,
  "losses": 19,
  "draws": 0,
  "max_elo": 1580,
  "min_elo": 1150,
  "current_streak": 3,
  "longest_win_streak": 7
}

Authentication

The Team Up API uses API keys for authentication. Include your key in the X-API-Key header.

Request Header

X-API-Key: your_api_key_here

Keep your API key secret. If compromised, delete it with /settings api_key delete and generate a new one with /settings api_key generate. Generating a new key does not automatically invalidate previous keys.

/settings api_key generate

Create a new API key for your server. Previous keys remain valid until deleted.

/settings api_key view

View your API keys (shown only to you).

/settings api_key delete

Delete a specific API key to revoke its access.

Format Parameter

Use the format query parameter to filter ratings by match type.

Format	Description
`(empty)`	Global ratings - all matches
`even`	Even team matches only
`1s, 2s, 3s...`	Player ratings by team size
`1v1, 2v2, 3v3...`	Player ratings by match format
`team-2s, team-3s...`	Team ratings by team size
`team-2v2, team-3v3...`	Team ratings by match format

Status Codes

Code	Meaning	Common Causes
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid parameters, malformed request
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	No active subscription
`404`	Not Found	Player, leaderboard, or resource not found
`429`	Rate Limited	Too many requests, try again later
`500`	Server Error	Internal error - please report if persistent

Postman Collection

A ready-to-use Postman collection is available with pre-configured requests for every endpoint. Import it to start testing the API immediately.

📦

Download

Download the collection file, then import it into Postman via File → Import.

Setup

After importing, configure the collection variables to match your server:

Variable	Description	Example
`base_url`	API base URL (pre-configured)	`https://api.teamupgg.com`
`client_id`	Your Discord server ID with DISCORD\| prefix	`DISCORD\|123456789`
`api_key`	Your API key from `/settings api_key generate`	`your_api_key`
`player_id`	A Discord user ID for testing	`92436985859293184`
`leaderboard`	Leaderboard name to query	`default`

Included Requests

REST Endpoints (Public)

GET Rankings (paginated)
GET Player Rating
GET Player Rank
GET Boosters
POST Batch Player Profiles
POST Batch Player Ratings
POST Batch Player Ranks

Action Endpoints (API Key)

POST Record Match (1v1, 2v2, FFA, Draw)
POST Record Match (Team Alias, Stats, Choices)
POST Record Match (with Deltas)
POST Undo Last Match
POST Set Player Rating
POST Sync Post Match

Related Resources

🔔

Webhooks

Receive real-time notifications when ratings change

📊

Rating Types

Understand the different rating types returned by the API

Endpoints

Base URL

https://api.teamupgg.com

Players

Matches

Players

Player ratings and profiles

get /v1/client/{client_id}/rankings

ApiKeyAuth

Get leaderboard rankings

get /v1/client/{client_id}/players/{player_id}/rating

ApiKeyAuth

Get player rating

get /v1/client/{client_id}/players/{player_id}/rank

ApiKeyAuth

Get player rank

get /v1/client/{client_id}/players/{player_id}/profile

ApiKeyAuth

Get player profile

post /v1/client/{client_id}/players/ratings

ApiKeyAuth

Batch get player ratings

post /v1/client/{client_id}/players/ranks

ApiKeyAuth

Batch get player ranks

get /v1/client/{client_id}/players/head-to-head

ApiKeyAuth

Get player head-to-head stats

post /v1/client/{client_id}/players/profiles

ApiKeyAuth

Batch get player profiles

Matches

Record matches and update ratings

get /v1/client/{client_id}/matches

ApiKeyAuth

Get match history

get /v1/client/{client_id}/matches/{leaderboard}

ApiKeyAuth

Get match history by leaderboard

get /v1/client/{client_id}/matches/{leaderboard}/{format}

ApiKeyAuth

Get match history by leaderboard and format

post /record_match

ApiKeyAuth

Record a match

post /record_match_with_deltas

ApiKeyAuth

Record a match with pre-computed deltas

post /undo_last_match

ApiKeyAuth

Undo the last match

post /sync_post_match

ApiKeyAuth

Sync post-match Discord side effects