Users Endpoint for the Top.gg v1 API

The users endpoints work with the user behind an OAuth access token. They require OAuth authentication; project tokens cannot call them.

GET /users/@me

Required scope: user.identify Returns the user who authorized your application.

curl https://top.gg/api/v1/users/@me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response fields

string

required

The user’s Top.gg Snowflake ID.

string

required

The user’s Top.gg username.

string

Avatar URL, or null when the user has none.

object[]

required

Platform accounts linked to the user.

Show Connection object properties

string

required

The platform. One of discord or roblox.

string

required

The user’s ID on that platform, for example their Discord user ID.

Example response

{
  "id": "1234567890",
  "username": "example",
  "avatar": "https://cdn.top.gg/avatars/1234567890.webp",
  "connections": [
    {
      "platform": "discord",
      "id": "1234567890"
    }
  ]
}

Error responses

Status	Description
`401`	Missing, expired, or revoked access token
`403`	The `user.identify` scope was not granted
`404`	The user no longer exists

GET /users/@me/projects

Required scope: user.projects.read Lists the projects owned by the user.

curl https://top.gg/api/v1/users/@me/projects \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response fields

Returns an array of project objects.

string

required

The Top.gg project ID.

string

required

The project’s ID on its platform, for example the Discord application ID.

string

required

The project name.

string

required

The platform. One of discord, roblox, or minecraft.

string

required

The project type, for example bot, server, or game.

string

required

The project headline.

string

required

The review state, for example draft, in_review, or approved.

Example response

[
  {
    "id": "218109768489992192",
    "platform_id": "1234567890",
    "name": "Example Bot",
    "platform": "discord",
    "type": "bot",
    "headline": "A bot that does things.",
    "review_status": "approved"
  }
]

POST /users/@me/projects

Required scope: user.projects.write Creates a draft project for the user. Name, icon, and missing descriptions are fetched from the platform. The project starts as a draft; the user completes the listing and submits it for review in their Top.gg dashboard.

curl -X POST https://top.gg/api/v1/users/@me/projects \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "discord",
    "type": "bot",
    "platform_id": "1234567890"
  }'

Request body

string

required

The platform the project lives on. One of discord, roblox, or minecraft.

string

required

The project type. bot or server for Discord, game for Roblox, game_server for Minecraft.

string

required

The project’s ID on the platform, for example the Discord application ID.

string

The headline shown on the project page, 3 to 140 characters. Defaults to the description found on the platform.

string

The page content in Markdown, 300 to 50,000 characters. Defaults to the description found on the platform.

Response

Returns 201 Created with the same project object as the list endpoint, with review_status set to draft.

Error responses

Status	Description
`409`	A project with this platform ID is already listed on Top.gg
`422`	Validation error, unsupported platform and type combination, or the project was not found on the platform

​GET /users/@me

​Response fields

​Example response

​Error responses

​GET /users/@me/projects

​Response fields

​Example response

​POST /users/@me/projects

​Request body

​Response

​Error responses

GET /users/@me

Response fields

Example response

Error responses

GET /users/@me/projects

Response fields

Example response

POST /users/@me/projects

Request body

Response

Error responses