REST API Endpoints for Projects

The projects endpoints let you retrieve a project’s details, update its headline, page content, and platform data, create announcements, and push updated command definitions to Top.gg. :project_id is the Top.gg project ID of a project your OAuth authorization covers, and each endpoint states its required scope. A project that is not part of the authorization returns 404. A missing scope returns 403.

Project tokens

With a legacy project token, use @me in place of :project_id. The token itself identifies the project. Project tokens only work with @me, and OAuth access tokens only work with explicit project IDs. Request bodies and responses are identical.

OAuth access token	Project token
`GET /projects/:project_id`	`GET /projects/@me`
`PATCH /projects/:project_id`	`PATCH /projects/@me`
`POST /projects/:project_id/announcements`	`POST /projects/@me/announcements`
`PATCH /projects/:project_id/metrics`	`PATCH /projects/@me/metrics`
`POST /projects/:project_id/metrics/batch`	`POST /projects/@me/metrics/batch`
`PUT /projects/:project_id/commands`	`PUT /projects/@me/commands`

Bot endpoints are subject to stricter rate limits than other v1 endpoints. Stay within the published limits to avoid 429 Too Many Requests responses.

GET /projects

OAuth scope: none, any valid access token or application token Lists the projects the current credential covers. With an access token that is the single project of the authorization. With an application token it is every project granted to your application, 100 per page. Not available with project tokens.

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

Query parameters

string

Cursor from a previous response to fetch the next page. Only meaningful with an application token.

Response fields

object[]

required

The covered projects.

Show Project object properties

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 the project belongs to. One of discord or roblox.

string

required

The project type. One of bot, server, or game.

string

Present while more pages exist. Pass it back as the cursor query parameter. Keep paging until the cursor is absent. A page can be empty while later pages still hold projects.

Example response

{
  "projects": [
    {
      "id": "218109768489992192",
      "platform_id": "1234567890",
      "name": "Example Bot",
      "platform": "discord",
      "type": "bot"
    }
  ]
}

GET /projects/:project_id

OAuth scope: project.information.read Returns the project associated with your current token.

curl https://top.gg/api/v1/projects/218109768489992192 \
  -H "Authorization: Bearer $TOPGG_TOKEN"

Response fields

string

required

The unique Top.gg-sourced Snowflake identifier for the project.

string

required

The project name as it appears on the external platform.

string

required

The platform the project belongs to. One of discord or roblox.

string

required

The project type. One of bot, server, or game.

string

required

The short description set during project creation.

string[]

required

List of tag IDs associated with the project.

number

required

Current vote count used for ranking calculations.

number

required

Total all-time votes received by the project.

number

required

Average review score across all reviews.

number

required

Total number of reviews submitted for the project.

Example response

{
  "id": "218109768489992192",
  "name": "Miki",
  "type": "bot",
  "platform": "discord",
  "headline": "A great bot with tons of features!",
  "tags": ["anime", "economy", "fun", "leveling"],
  "votes": 1120,
  "votes_total": 313389,
  "review_score": 4.38,
  "review_count": 62245
}

PATCH /projects/:project_id

OAuth scope: project.information.write Updates the headline, page content, and/or platform data for your project. headline and page_content are locale-keyed, so you can set content for multiple languages in a single request.

curl -X PATCH https://top.gg/api/v1/projects/218109768489992192 \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": {
      "en": "A great bot with tons of features!"
    },
    "page_content": {
      "en": "# Welcome\nThis is the full page description for your project..."
    }
  }'

Platform data goes in additional_data, under the key for your project’s platform. For example, to set a Minecraft server’s address:

curl -X PATCH https://top.gg/api/v1/projects/218109768489992192 \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_data": {
      "minecraft_server": {
        "host": "play.example.com",
        "port": 25565
      }
    }
  }'

Request body

At least one of headline, page_content, or additional_data must be provided.

object

A map of locale codes to headline strings. Each headline must be between 3 and 140 characters.

object

A map of locale codes to page content strings (Markdown supported). Each entry must be between 300 and 50,000 characters.

object

Data that only applies to your project’s platform, with one object per platform. Only the object for your project’s platform is accepted. Sending another returns 422. Omitted fields keep their current value. Only works with an OAuth access token. PATCH /projects/@me returns 422 when it is set.

Show Additional data properties

Supported locales

en, de, fr, pt, tr, hi, ja, ar, nl, ko, it, es, ru, uk, vi, zh

Response

Returns 204 No Content on success. No response body is returned.

Changes may take up to 1 hour to appear on the website due to caching.

Error responses

Status	Description
`400`	Invalid project token
`404`	Project not found
`422`	Validation error (unsupported locale, length violations, missing fields, or `additional_data` the project’s platform doesn’t accept)

POST /projects/:project_id/announcements

OAuth scope: project.announcements.write Creates a new announcement for your project. Announcements appear on your project’s page and can be used to notify users about updates, new features, or other news.

You can create at most one announcement every 4 hours. Attempts during the cooldown period receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

curl -X POST https://top.gg/api/v1/projects/218109768489992192/announcements \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Version 2.0 Released!",
    "content": "We just released version 2.0 with a bunch of new features and improvements.",
    "category": "new_feature"
  }'

Request body

string

required

The announcement title. Must be between 3 and 100 characters.

string

required

The announcement body text. Must be between 10 and 2,000 characters.

string

The category to publish the announcement under. One of announcement, event, or new_feature. Defaults to announcement when omitted.

Response fields

string

required

The title of the created announcement.

string

required

The body content of the created announcement.

string

required

ISO 8601 timestamp of when the announcement was created.

Example response

{
  "title": "Version 2.0 Released!",
  "content": "We just released version 2.0 with a bunch of new features and improvements.",
  "created_at": "2026-03-14T15:09:26Z"
}

Error responses

Status	Description
`400`	Invalid project token
`404`	Project not found
`422`	Validation error (title or content length violations, or unsupported category)
`429`	Rate limited - only one announcement every 4 hours

PATCH /projects/:project_id/metrics

OAuth scope: project.metrics.write Submits a single metrics payload for your project. Use this to push fresh numbers after an event such as joining or leaving a guild or a player connecting.

curl -X PATCH https://top.gg/api/v1/projects/218109768489992192/metrics \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_count": 420,
    "shard_count": 67
  }'

Request body

The body must match the authenticated project’s platform. See the platform payloads section below for the supported fields per platform.

Response

Returns 204 No Content on success. No response body is returned.

Error responses

Status	Description
`400`	Invalid project token
`404`	Project not found
`422`	Payload was malformed, empty, or did not match the project’s platform

POST /projects/:project_id/metrics/batch

OAuth scope: project.metrics.write Submits up to 100 metrics entries in a single request. Entries without a timestamp are applied first in the order they appear in the request. Entries with a timestamp are applied afterward in ascending timestamp order, so you can backfill gaps or push buffered samples after a network interruption.

curl -X POST https://top.gg/api/v1/projects/218109768489992192/metrics/batch \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "timestamp": "2026-04-17T10:00:00Z",
        "metrics": { "server_count": 419 }
      },
      {
        "timestamp": "2026-04-17T10:05:00Z",
        "metrics": { "server_count": 420, "shard_count": 67 }
      }
    ]
  }'

Request body

object[]

required

The batch of metrics entries. Must contain between 1 and 100 entries.

Show Entry object properties

Response

Returns 204 No Content when every entry is accepted. If any entry fails validation, processing stops and the request returns 422.

Error responses

Status	Description
`400`	Invalid project token
`404`	Project not found
`422`	Batch was empty, contained more than 100 entries, or contained an invalid entry

Platform payloads

The metrics payload is shaped per platform. For PATCH /projects/:project_id/metrics, send this payload as the request body. For the batch metrics endpoint, send the same payload under data[].metrics. Sending the wrong shape for your project returns 422.

Discord bot

Use for projects with platform: "discord" and type: "bot". At least one field is required.

integer

Total number of servers the bot is currently in. Must be zero or greater.

integer

Total number of shards the bot is currently running. Must be zero or greater.

{
  "server_count": 420,
  "shard_count": 67
}

Discord server

Use for projects with platform: "discord" and type: "server". At least one field is required.

integer

Total number of members in the server. Must be zero or greater.

integer

Number of members currently online. Must be zero or greater and cannot exceed member_count when both are provided.

{
  "member_count": 14820,
  "online_count": 3120
}

Roblox game

Use for projects with platform: "roblox" and type: "game".

integer

required

Current number of players in the game. Must be zero or greater.

{
  "player_count": 428
}

PUT /projects/:project_id/commands

OAuth scope: project.information.write Overwrites the list of slash command definitions for your bot project on Top.gg. This endpoint is only applicable to bot-type projects on the discord platform.

curl -X PUT https://top.gg/api/v1/projects/218109768489992192/commands \
  -H "Authorization: Bearer $TOPGG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{ "name": "ping", "description": "Replies with Pong!" }]'

Request body

The request body must be a JSON array of command objects following Discord’s application command structure. Pass an empty array to clear all commands.

object[]

required

Array of application command objects following Discord’s application command structure.

Response

Returns 204 No Content on success. No response body is returned.

v1 API

Legacy v0 API

REST API Endpoints for Projects

Project tokens

GET /projects

Query parameters

Response fields

Example response

GET /projects/:project_id

Response fields

Example response

PATCH /projects/:project_id

Request body

Supported locales

Response

Error responses

POST /projects/:project_id/announcements

Request body

Response fields

Example response

Error responses

PATCH /projects/:project_id/metrics

Request body

Response

Error responses

POST /projects/:project_id/metrics/batch

Request body

Response

Error responses

Platform payloads

Discord bot

Discord server

Roblox game

PUT /projects/:project_id/commands

Request body

Response